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/truffle-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 | External programmatic description of contract's interface. The contract's ABI
|
60 | determines the means by which applications may interact with individual contract
|
61 | instances. Array of functions and events representing valid inputs and outputs
|
62 | for the instance.
|
63 |
|
64 |
|
65 | ### `ast`
|
66 |
|
67 | | type | _object_ |
|
68 | | ---: | ---- |
|
69 |
|
70 | _not included in current version of this specification_
|
71 |
|
72 | Abstract Syntax Tree. A nested JSON object representation of contract source
|
73 | code, as output by compiler.
|
74 |
|
75 |
|
76 |
|
77 | ### `bytecode`
|
78 |
|
79 | | type | _string_ matching pattern `^0x0$\|^0x([a-fA-F0-9]{2}\|__.{38})+$` |
|
80 | | ---: | ---- |
|
81 | | ref | [Bytecode](#contract-object--bytecode) |
|
82 |
|
83 |
|
84 | EVM instruction bytecode that runs as part of contract create transaction.
|
85 | Constructor code for new contract instance.
|
86 | Specified as a hexadecimal string, may include `__`-prefixed (double underscore)
|
87 | link references.
|
88 |
|
89 |
|
90 |
|
91 | ### `deployedBytecode`
|
92 |
|
93 | | type | _string_ matching pattern `^0x0$\|^0x([a-fA-F0-9]{2}\|__.{38})+$` |
|
94 | | ---: | ---- |
|
95 | | ref | [Bytecode](#contract-object--bytecode) |
|
96 |
|
97 |
|
98 | EVM instruction bytecode associated with contract that specifies behavior for
|
99 | incoming transactions/messages. Underlying implementation of ABI.
|
100 | Specified as a hexadecimal string, may include `__`-prefixed (double underscore)
|
101 | link references.
|
102 |
|
103 |
|
104 | ### `source`
|
105 |
|
106 | | type | _string_ |
|
107 | | ---: | ---- |
|
108 |
|
109 |
|
110 | Uncompiled source code for contract. Text string.
|
111 |
|
112 |
|
113 | ### `sourcePath`
|
114 |
|
115 | | type | _string_ |
|
116 | | ---: | ---- |
|
117 |
|
118 | File path for uncompiled source code.
|
119 |
|
120 |
|
121 | ### `sourceMap`
|
122 |
|
123 | | type | _string_ matching pattern `^[0-9;]*` |
|
124 | | ---: | ---- |
|
125 |
|
126 |
|
127 | Source mapping for `bytecode`, pairing contract creation transaction data bytes
|
128 | with origin statements in uncompiled `source`.
|
129 |
|
130 |
|
131 | ### `deployedSourceMap`
|
132 |
|
133 | | type | _string_ matching pattern `^[0-9;]*` |
|
134 | | ---: | ---- |
|
135 |
|
136 | Source mapping for `deployedBytecode`, pairing contract program data bytes
|
137 | with origin statements in uncompiled `source`.
|
138 |
|
139 |
|
140 | ### `schemaVersion`
|
141 |
|
142 | | type | _string_ matching pattern `[0-9]+\.[0-9]+\.[0-9]+` |
|
143 | | ---: | ---- |
|
144 |
|
145 | Version of this schema used by contract object representation.
|
146 |
|
147 |
|
148 |
|
149 | ### `updatedAt`
|
150 |
|
151 | | type | _string_ |
|
152 | | ---: | ---- |
|
153 | | format | IS0-8601 Datetime |
|
154 |
|
155 |
|
156 | Time at which contract object representation was generated/most recently
|
157 | updated.
|
158 |
|
159 |
|
160 | ### `networks`
|
161 |
|
162 | | type | _object_ |
|
163 | | ---: | ---- |
|
164 |
|
165 | Listing of contract instances. Object mapping network ID keys to network object
|
166 | values. Includes address information, links to other contract instances, and/or
|
167 | contract event logs.
|
168 |
|
169 | #### Properties (key matching `^[a-zA-Z0-9]+$`)
|
170 |
|
171 | | type | _object_ |
|
172 | | ---: | ---- |
|
173 | | ref | [Network Object](network-object.spec.md) |
|
174 |
|
175 |
|
176 | ## Custom Properties
|
177 |
|
178 | ### `^x-([a-zA-Z]+-)*[a-zA-Z]+`
|
179 |
|
180 | | type | _string or number or object or array_ |
|
181 | | ---: | ---- |
|
182 |
|
183 | Objects following this schema may include additional properties with
|
184 | `x-`-prefixed keys.
|
185 |
|
186 |
|
187 |
|
188 | ## Definitions
|
189 |
|
190 |
|
191 |
|
192 |
|
193 | ### <a name="contract-object--bytecode">Bytecode</a>
|
194 |
|
195 | | type | _string_ matching pattern `^0x0$\|^0x([a-fA-F0-9]{2}\|__.{38})+$` |
|
196 | | ---: | ---- |
|
197 |
|
198 | `0x`-prefixed string representing compiled EVM machine language.
|
199 |
|
200 | This string representation may indicate link references in place of
|
201 | linked instance addresses. Link references must begin with `__` and be exactly
|
202 | 40 characters long (i.e., string length of an address in hexadecimal).
|