0
# Contract Creation and Management
1

2
Core contract instantiation, configuration management, and Web3 context integration for the web3-eth-contract library.
3

4
## Capabilities
5

6
### Contract Constructor
7

8
Creates a new contract instance with all its methods and events defined in its ABI.
9

10
```typescript { .api }
11
/**
12
 * Creates a new contract instance with all its methods and events defined in its ABI
13
 * @param jsonInterface - The JSON interface (ABI) for the contract to instantiate
14
 * @param address - The address of the smart contract to call (optional)
15
 * @param options - The options of the contract used as fallbacks for calls and transactions
16
 * @param context - The context of the contract used for customizing behavior
17
 */
18
class Contract<Abi extends ContractAbi> {
19
  constructor(jsonInterface: Abi);
20
  constructor(jsonInterface: Abi, context: Web3ContractContext | Web3Context);
21
  constructor(jsonInterface: Abi, address: Address, contextOrReturnFormat?: Web3ContractContext | Web3Context | DataFormat);
22
  constructor(jsonInterface: Abi, options: ContractInitOptions, contextOrReturnFormat?: Web3ContractContext | Web3Context | DataFormat);
23
  constructor(jsonInterface: Abi, address: Address, options: ContractInitOptions, contextOrReturnFormat?: Web3ContractContext | Web3Context | DataFormat);
24
}
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import { Contract } from "web3-eth-contract";
31

32
// Basic contract with ABI only
33
const abi = [...] as const;
34
const contract = new Contract(abi);
35

36
// Contract with address
37
const contract = new Contract(abi, "0x1234567890123456789012345678901234567890");
38

39
// Contract with options
40
const contract = new Contract(abi, {
41
  from: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
42
  gas: 1000000,
43
  gasPrice: "20000000000"
44
});
45

46
// Contract with address and options
47
const contract = new Contract(
48
  abi,
49
  "0x1234567890123456789012345678901234567890",
50
  {
51
    from: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
52
    gas: 1000000
53
  }
54
);
55
```
56

57
### Contract Options
58

59
The options object for the contract instance containing fallback values for transactions.
60

61
```typescript { .api }
62
interface ContractOptions {
63
  /** The address of the smart contract */
64
  address?: Address;
65
  /** The JSON interface (ABI) for the contract */
66
  jsonInterface?: ContractAbi;
67
  /** Default gas limit for contract interactions */
68
  gas?: Numbers;
69
  /** Default gas price in wei */
70
  gasPrice?: Numbers;
71
  /** Default from address for transactions */
72
  from?: Address;
73
  /** Contract bytecode input (alias for data) */
74
  input?: HexString;
75
  /** Contract bytecode data */
76
  data?: HexString;
77
}
78

79
interface ContractInitOptions extends ContractOptions {
80
  /** Web3 provider for the contract */
81
  provider?: SupportedProviders;
82
}
83
```
84

85
**Usage Examples:**
86

87
```typescript
88
// Access and modify contract options
89
console.log(contract.options.address);
90
console.log(contract.options.gas);
91

92
// Set default values
93
contract.options.from = "0x1234567890123456789012345678901234567891";
94
contract.options.gasPrice = "20000000000";
95
contract.options.gas = 5000000;
96

97
// These will be used as fallbacks for method calls
98
const receipt = await contract.methods.someMethod().send(); // Uses options.from and options.gas
99
```
100

101
### Contract Context
102

103
Web3 context configuration for customizing contract behavior.
104

105
```typescript { .api }
106
type Web3ContractContext = Partial<{
107
  /** Web3 provider instance */
108
  provider: SupportedProviders;
109
  /** Web3 request manager for RPC calls */
110
  requestManager: Web3RequestManager;
111
  /** Web3 configuration settings */
112
  config: Web3Configuration;
113
}>;
114
```
115

116
### Sync with Context
117

118
Control whether contract defaults sync with global Web3 context defaults.
119

120
```typescript { .api }
121
class Contract<Abi extends ContractAbi> {
122
  /** Set to true if you want contracts' defaults to sync with global defaults */
123
  syncWithContext: boolean;
124
}
125
```
126

127
**Usage Examples:**
128

129
```typescript
130
// Enable syncing with global context
131
contract.syncWithContext = true;
132

133
// Now contract will automatically use global Web3 settings
134
// Changes to web3.defaultAccount, web3.defaultGasPrice, etc. will be reflected
135
```
136

137
### Address Management
138

139
Get and set the contract address after instantiation.
140

141
```typescript { .api }
142
class Contract<Abi extends ContractAbi> {
143
  /** The address of the smart contract */
144
  readonly options: ContractOptions & {
145
    address?: Address;
146
  };
147
}
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
// Check current contract address
154
if (contract.options.address) {
155
  console.log("Contract deployed at:", contract.options.address);
156
} else {
157
  console.log("Contract not yet deployed");
158
}
159

160
// Set address after deployment
161
contract.options.address = deployedContractAddress;
162
```
163

164
### Clone Contract
165

166
Create a new contract instance with the same ABI but different address or options.
167

168
```typescript { .api }
169
class Contract<Abi extends ContractAbi> {
170
  /**
171
   * Creates a new contract instance with the same ABI
172
   * @param address - New contract address
173
   * @param options - New contract options
174
   * @returns New Contract instance
175
   */
176
  clone(address?: Address, options?: ContractOptions): Contract<Abi>;
177
}
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
// Clone contract for different address
184
const proxyContract = contract.clone("0x9876543210987654321098765432109876543210");
185

186
// Clone with different options
187
const contractWithDifferentDefaults = contract.clone(undefined, {
188
  from: "0xdifferentaddress",
189
  gas: 2000000
190
});
191
```
192

193
### Transaction Middleware
194

195
Access to transaction middleware for advanced transaction processing.
196

197
```typescript { .api }
198
class Contract<Abi extends ContractAbi> {
199
  /**
200
   * Set transaction middleware for advanced transaction processing
201
   * @param transactionMiddleware - The middleware instance to set
202
   */
203
  setTransactionMiddleware(transactionMiddleware: TransactionMiddleware): void;
204
  
205
  /**
206
   * Get the current transaction middleware
207
   * @returns The transaction middleware instance if set
208
   */
209
  getTransactionMiddleware(): TransactionMiddleware | undefined;
210
}
211
```
212

213
**Usage Examples:**
214

215
```typescript
216
// Set transaction middleware
217
const customMiddleware = new CustomTransactionMiddleware();
218
contract.setTransactionMiddleware(customMiddleware);
219

220
// Check if transaction middleware is configured
221
const middleware = contract.getTransactionMiddleware();
222
if (middleware) {
223
  console.log("Transaction middleware is configured");
224
} else {
225
  console.log("No transaction middleware set");
226
}
227
```
228

229
### Method Data Decoding
230

231
Decode transaction input data to understand which method was called and with what parameters.
232

233
```typescript { .api }
234
class Contract<Abi extends ContractAbi> {
235
  /**
236
   * Decode method data from transaction input to reveal method name and parameters
237
   * @param data - The transaction input data to decode
238
   * @returns Decoded parameters with method information
239
   */
240
  decodeMethodData(data: HexString): DecodedParams & { __method__: string };
241
}
242
```
243

244
**Usage Examples:**
245

246
```typescript
247
// Decode transaction data
248
const transactionData = "0xa9059cbb000000000000000000000000abcdefabcdefabcdefabcdefabcdefabcdefabcdef0000000000000000000000000000000000000000000000000de0b6b3a7640000";
249

250
const decoded = contract.decodeMethodData(transactionData);
251
console.log("Method called:", decoded.__method__); // "transfer(address,uint256)"
252
console.log("Number of parameters:", decoded.__length__); // 2
253
console.log("To address:", decoded.to || decoded[0]);
254
console.log("Amount:", decoded.amount || decoded[1]);
255

256
// Access parameters by name (if available in ABI)
257
if (decoded.to && decoded.amount) {
258
  console.log(`Transfer ${decoded.amount} tokens to ${decoded.to}`);
259
}
260

261
// Access parameters by index (always available)
262
console.log(`Parameter 0: ${decoded[0]}`);
263
console.log(`Parameter 1: ${decoded[1]}`);
264
```
265

266
## Error Handling
267

268
```typescript { .api }
269
// Web3 contract-specific errors
270
class Web3ContractError extends Web3Error {
271
  constructor(message: string, receipt?: TransactionReceipt);
272
}
273

274
class ContractExecutionError extends Web3ContractError {
275
  constructor(receipt: TransactionReceipt);
276
}
277

278
class ContractTransactionDataAndInputError extends Web3ContractError {
279
  constructor();
280
}
281
```