1 | # Schema Description: Truffle Contract Object
|
2 |
|
3 | | type | _object_ |
|
4 | | ---: | ---- |
|
5 | | JSON Schema | [contract-object.spec.json](spec/contract-object.spec.json) |
|
6 |
|
7 |
|
8 | [@truffle/contract](https://github.com/trufflesuite/truffle/tree/develop/packages/contract) uses a
|
9 | formally specified<sup>[1](#footnote-1)</sup> JSON object format to represent
|
10 | Ethereum Virtual Machine (EVM) smart contracts. This representation is intended
|
11 | to facilitate the use of general purpose smart contract abstractions
|
12 | (such as @truffle/contract) by capturing relevant smart contract information in a
|
13 | persistent and portable manner.
|
14 |
|
15 | Objects following this schema represent individual smart contracts as defined
|
16 | by their name and interface. Each object primarily includes a JSON array
|
17 | representing the contract's ABI<sup>[2](#footnote-2)</sup>, but extends to
|
18 | include any and all information related to the contract and its lifecycle(s).
|
19 | Objects in this schema may represent pre-compiled source code, compilation
|
20 | annotations such as source mappings, references to specified deployed instances
|
21 | on multiple networks, and/or links to external contracts.
|
22 |
|
23 | A full property listing is below. Properties not marked "**required**" are not
|
24 | necessary to include in valid descriptions of contract objects, but functionally
|
25 | certain information must be present to allow the contract object representation
|
26 | to be useful (`source`/`bytecode`/etc. enable the deployment of new instances,
|
27 | `networks` listed with prior contract instance `address`es enable interaction
|
28 | with deployed contracts on-chain)
|
29 |
|
30 |
|
31 | ## References
|
32 |
|
33 | <a name="footnote-1">1.</a> JSON Schema [http://json-schema.org](http://json-schema.org/)
|
34 |
|
35 | <a name="footnote-2">2.</a> Ethereum Contract JSON ABI [https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#json](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#json)
|
36 |
|
37 |
|
38 |
|
39 | ## Properties
|
40 |
|
41 |
|
42 | ### `contractName`
|
43 |
|
44 | | type | _string_ matching pattern `^[a-zA-Z_][a-zA-Z0-9_]*$` |
|
45 | | ---: | ---- |
|
46 | | default | `"Contract"` |
|
47 |
|
48 |
|
49 | Name used to identify the contract. Semi-alphanumeric string.
|
50 |
|
51 |
|
52 | ### `abi`
|
53 |
|
54 | | type | _array_ |
|
55 | | ---: | ---- |
|
56 | | JSON Schema | [abi.spec.json](spec/abi.spec.json) |
|
57 | | **required** |
|
58 |
|
59 |
|
60 | External programmatic description of contract's interface. The contract's ABI
|
61 | determines the means by which applications may interact with individual contract
|
62 | instances. Array of functions and events representing valid inputs and outputs
|
63 | for the instance.
|
64 |
|
65 |
|
66 | ### `metadata`
|
67 |
|
68 | | type | _string_ |
|
69 | | ---: | ---- |
|
70 |
|
71 |
|
72 | Contract metadata. Stringified JSON.
|
73 |
|
74 |
|
75 |
|
76 | ### `bytecode`
|
77 |
|
78 | | type | _string_ matching pattern `^0x0$\|^0x([a-fA-F0-9]{2}\|__.{38})+$` |
|
79 | | ---: | ---- |
|
80 | | ref | [Bytecode](#contract-object--bytecode) |
|
81 |
|
82 |
|
83 | EVM instruction bytecode that runs as part of contract create transaction.
|
84 | Constructor code for new contract instance.
|
85 | Specified as a hexadecimal string, may include `__`-prefixed (double underscore)
|
86 | link references.
|
87 |
|
88 |
|
89 | ### `deployedBytecode`
|
90 |
|
91 | | type | _string_ matching pattern `^0x0$\|^0x([a-fA-F0-9]{2}\|__.{38})+$` |
|
92 | | ---: | ---- |
|
93 | | ref | [Bytecode](#contract-object--bytecode) |
|
94 |
|
95 |
|
96 | EVM instruction bytecode associated with contract that specifies behavior for
|
97 | incoming transactions/messages. Underlying implementation of ABI.
|
98 | Specified as a hexadecimal string, may include `__`-prefixed (double underscore)
|
99 | link references.
|
100 |
|
101 |
|
102 | ### `sourceMap`
|
103 |
|
104 | | type | _string_ matching pattern `^[0-9;]*` |
|
105 | | ---: | ---- |
|
106 |
|
107 |
|
108 | Source mapping for `bytecode`, pairing contract creation transaction data bytes
|
109 | with origin statements in uncompiled `source`.
|
110 |
|
111 |
|
112 | ### `deployedSourceMap`
|
113 |
|
114 | | type | _string_ matching pattern `^[0-9;]*` |
|
115 | | ---: | ---- |
|
116 |
|
117 |
|
118 | Source mapping for `deployedBytecode`, pairing contract program data bytes
|
119 | with origin statements in uncompiled `source`.
|
120 |
|
121 |
|
122 | ### `source`
|
123 |
|
124 | | type | _string_ |
|
125 | | ---: | ---- |
|
126 |
|
127 |
|
128 | Uncompiled source code for contract. Text string.
|
129 |
|
130 |
|
131 | ### `sourcePath`
|
132 |
|
133 | | type | _string_ |
|
134 | | ---: | ---- |
|
135 |
|
136 |
|
137 | File path for uncompiled source code.
|
138 |
|
139 |
|
140 | ### `ast`
|
141 |
|
142 | | type | _object_ |
|
143 | | ---: | ---- |
|
144 |
|
145 |
|
146 | _format not included in current version of this specification_
|
147 |
|
148 | Abstract Syntax Tree. A nested JSON object representation of contract source
|
149 | code, as output by compiler.
|
150 |
|
151 |
|
152 | ### `legacyAST`
|
153 |
|
154 | | type | _object_ |
|
155 | | ---: | ---- |
|
156 |
|
157 |
|
158 | _format not included in current version of this specification_
|
159 |
|
160 | Legacy Abstract Syntax Tree. A nested JSON object representation of contract source
|
161 | code, as output by compiler.
|
162 |
|
163 |
|
164 | ### `compiler`
|
165 |
|
166 | | type | _object_ |
|
167 | | ---: | ---- |
|
168 |
|
169 |
|
170 | Compiler information.
|
171 |
|
172 |
|
173 | ### `name`
|
174 |
|
175 | | type | string |
|
176 | | ---: | ---- |
|
177 |
|
178 |
|
179 | Name of the compiler used.
|
180 |
|
181 |
|
182 | ### `version`
|
183 |
|
184 | | type | string |
|
185 | | ---: | ---- |
|
186 |
|
187 |
|
188 | Version of the compiler used.
|
189 |
|
190 |
|
191 | ### `networks`
|
192 |
|
193 | | type | _object_ |
|
194 | | ---: | ---- |
|
195 |
|
196 |
|
197 | Listing of contract instances. Object mapping network ID keys to network object
|
198 | values. Includes address information, links to other contract instances, and/or
|
199 | contract event logs.
|
200 |
|
201 |
|
202 | #### Properties (key matching `^[a-zA-Z0-9]+$`)
|
203 |
|
204 | | type | _object_ |
|
205 | | ---: | ---- |
|
206 | | ref | [Network Object](network-object.spec.md) |
|
207 |
|
208 |
|
209 | ### `schemaVersion`
|
210 |
|
211 | | type | _string_ matching pattern `[0-9]+\.[0-9]+\.[0-9]+` |
|
212 | | ---: | ---- |
|
213 |
|
214 |
|
215 | Version of this schema used by contract object representation.
|
216 |
|
217 |
|
218 | ### `updatedAt`
|
219 |
|
220 | | type | _string_ |
|
221 | | ---: | ---- |
|
222 | | format | IS0-8601 Datetime |
|
223 |
|
224 |
|
225 | Time at which contract object representation was generated/most recently
|
226 | updated.
|
227 |
|
228 |
|
229 | ### `networkType`
|
230 |
|
231 | | type | string |
|
232 | | ---: | ---- |
|
233 | | default | `"ethereum"` |
|
234 |
|
235 |
|
236 | Specific blockchain network type targeted.
|
237 |
|
238 |
|
239 | ### `devdoc`
|
240 |
|
241 | | type | string |
|
242 | | ---: | ---- |
|
243 |
|
244 |
|
245 | NatSpec developer documentation of the contract.
|
246 |
|
247 |
|
248 | ### `userdoc`
|
249 |
|
250 | | type | string |
|
251 | | ---: | ---- |
|
252 |
|
253 |
|
254 | NatSpec user documentation of the contract.
|
255 |
|
256 |
|
257 | ## Custom Properties
|
258 |
|
259 | ### `^x-([a-zA-Z]+-)*[a-zA-Z]+`
|
260 |
|
261 | | type | _string or number or object or array_ |
|
262 | | ---: | ---- |
|
263 |
|
264 |
|
265 | Objects following this schema may include additional properties with
|
266 | `x-`-prefixed keys.
|
267 |
|
268 |
|
269 | ## Definitions
|
270 |
|
271 |
|
272 | ### <a name="contract-object--bytecode">Bytecode</a>
|
273 |
|
274 | | type | _string_ matching pattern `^0x0$\|^0x([a-fA-F0-9]{2}\|__.{38})+$` |
|
275 | | ---: | ---- |
|
276 |
|
277 |
|
278 | `0x`-prefixed string representing compiled EVM machine language.
|
279 |
|
280 | This string representation may indicate link references in place of
|
281 | linked instance addresses. Link references must begin with `__` and be exactly
|
282 | 40 characters long (i.e., string length of an address in hexadecimal).
|