Skip to content

EIP-0005: Contract Template Documentation#

Overview#

Author: aslesarenko
Status: Proposed
Created: 06-Apr-2020
License: CC0
Forking: Not Needed

Table of Contents#

Description#

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
... ... ... ...

Note: See the original EIP-0005 document for complete field descriptions and further details.

Parameter Serialization Format#

This section provides the binary serialization format for parameters within contract templates.

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.