EIP-0005: Contract Template Documentation
Back to StandardsOverview
EIP-0005 outlines a standard for serializing contract templates and including metadata to make them reusable across multiple platforms. It aims to provide a way for developers to easily move contract templates between different protocol implementations, applications, and tools.
Background And Motivation
Ergo employs a robust language, known as ErgoTree, to create guarding propositions that protect UTXO boxes. While ErgoTree's serialization is efficient for storage and transaction validation, it lacks the metadata necessary for broader application use. This EIP aims to extend ErgoTree's capabilities by adding serialization formats for contract templates, including metadata for more versatile applications.
Example Use Cases
- ErgoTree compilers can generate contract templates complete with necessary metadata.
- Contract templates generated by one compiler (e.g., ErgoScala) can be used in environments where specific libraries (e.g., Java jar generated by Scala2.12) are not supported.
- The contract template becomes a self-contained entity, making it easier to store, transfer, parse, or execute across different platforms and tools.
Contract Template Serialization Format
This section provides the binary serialization format for contract templates, optimized for compact storage and wire transfer. Below is a table illustrating the fields and their formats:
| Field Name | Format | Example | Description |
|---|---|---|---|
| TreeVersion | Opt[UByte] | 1 | Optional version of ErgoTree to be used |
| NameLength | VLQ(UInt) | 18 | Length of Name in bytes |
| Name | Bytes | "rewardOutputScript" | User-readable name of the contract |
| DescLength | VLQ(UInt) | 20 | Length of Description in bytes |
| Description | Bytes | "holds mining rewards" | User-readable contract description |
| ... | ... | ... | ... |
See the original EIP-0005 document for complete field descriptions and further details.
Parameter Serialization Format
| Field Name | Format | Example | Description |
|---|---|---|---|
| NameLength | VLQ(UInt) | 7 | Length of Name in bytes |
| Name | Bytes | "minerPk" | User-readable parameter name |
| DescLength | VLQ(UInt) | 18 | Length of Description in bytes |
| Description | Bytes | "miner's public key" | User-readable parameter description |
| ConstantIndex | VLQ(UInt) | 1 | Index in the ErgoTree.constants array |
JSON Format
Contract templates can also be serialized into JSON format, suitable for applications that require human-readable or editable templates. A sample JSON representation is as follows:
{
"name": "rewardOutputScript",
"description": "holds mining rewards",
...
}Conversion to ErgoTree
This section outlines how to convert a contract template into an ErgoTree structure. The conversion allows for the substitution of new values for the constants in the template, either redefining the default values or providing missing ones.
Notes on Supporting this EIP in ErgoTree Compilers
Compilers like ErgoScript and ErgoScala can easily incorporate this EIP by generating templates packaged as either JSON or bytes. Annotations in the source code can also aid the compiler in generating the appropriate metadata and serialization formats.
For complete technical details and field specifications, refer to the original EIP-0005 document.