Skip to main content

Specification

Overview​

Codigo Generator is a set of tools and engines to generate “Smart Contracts” stubs, Client code and documentation from a Codigo’s Interface Description Language or CIDL file.

“Smart Contract” stubs are generated in full source, verified and audited, code. Developers will need to only implement the business logic for each stub, avoiding the repetitive boilerplate code for validation, verification and parsing.

Client Code generation supports multiple programming languages. It takes a CIDL as input and generates full client compilable code. The client code includes all the necessary elements to call the Smart Contract methods through the underlying Blockchain.

Interacting with a Smart Contract is already possible via the RPC interfaces exposed by Blockchains Clients and Validators. However, writing the boilerplate code that translates a programming language construct into RPC calls and back is time-consuming, prone to errors and brittle - implementation bugs and security vulnerabilities can only be detected during runtime.

Goals​

Codigo’s main goal is to speed Blockchain adoption by enabling Developers to focus on their business logic while Codigo Generator takes care of all the rest.

  1. Generates “Smart Contract” boilerplate and stubs Codigo Generator abstracts all the initialization, validation, verification and parsing for each incoming request, and routes the call to the specific stub method with all parameters validated and sanitized.

  2. Generates Client Libraries Codigo Generators simplifies Smart Contract adoption by generating “Smart Contract” client libraries in multiple programming languages. Method calls are abstracted behind a simple API interface. All the boilerplate code to generate the actual Blockchain Smart Contract call is automatically generated by Codigo Generators for each programming language.

  3. Documentation Codigo Generators creates full Smart Contract documentation based on the CIDL file. This documentation will list all exposed methods by the Smart Contract and input parameters. For Account based VMs, like Solana, full account structure is documented as well. The details of the documentation are an integral part of the CIDL file.

Codigo’s Interface Description Language CIDL​

CIDL is a work in progress, open initiative to standardize how Smart Contracts Interfaces and data structures are described.

The Codigo Interface Description Language defines a programming language-agnostic, interface description for Smart Contract Interfaces and custom data types, which allows both humans and computers to discover and understand the capabilities of a Smart Contract without requiring access to source code, additional documentation, or reverse engineering. The CIDL Specification removes guesswork in calling a Smart Contract.

CIDL Schema Definition​

tip

CIDL Specification is a WIP. You can contribute to this specification by opening an issues in the Código Platform Repo

cidl: CIDL version
info: # Metadata of the smart contract
  name: smart contract name
  title: title or name of the smart contract
  version: version of the smart contract
  summary: smart contract description summary
  contact:
    name: contact name | company
    web: url of company | support
    email: email of contact | support
    git: git URL
  license:
    name: license name
    identifier: SPDX license expression
    url: license URL

imports: # Array external CIDLs
  - ref: name | name to be referenced inside this document.
    loc: url [ local file system, https, github ]
    solana:
      progid: pubkey | ID of the Program generated by the external CIDL

solana:
  seeds:
    <seed-name>: # Identifier for this seed definition
      bump: hardcoded bump value
      persist-bump: bump should be persisted or not
      items: # Array of seed's element, static or dynamic
        - name: literal value or variable name
          type: native or extended type, required to define dynamic seeds

types:
  <type-name>: # Identifier for this Structure
    summary: type description summary
    fields: # Array of fields
      - name: field name
        type: native | extended (with some exception) data type
        description: field description
        format: The format of this field [date-time, key, etc]
        attributes: Attribute to apply to the type [max=nn, min=nn, cap=nn]

methods: # Array of methods | instructions
  - name: method name
    summary: description of this method
    solana:
      default-payer: boolean, if false disables the default fee payer. Only applicable if signers are not defined
      compress: # Array of types that should be compressed
        - type: reference to a custom-defined type
          mode: append | insert_or_append | replace_leaf | verify_leaf
    signers: # Array of signers
      - name: signer name
        type: native | extended (with some exception) data type
      - input: input name, when set, the input will be mark as a signer
    uses: # Array of string
      - import_ref.method_name
    inputs: # Array of inputs
      - name: input name
        type: [ import_ref. ] native | custom-defined type | extended
        description: short description of this input parameter
        attributes: Attribute to apply to the type [sol:init, sol:writable, cap=nn]

errors: # Array - Custom Errors definition
  - id: ErrorIdentifier
    msg: Error message

Metadata​

In this section the developer defines Smart Contract general settings, such as Smart Contract Name, Version and a full description of the Smart Contract capabilities to be parsed by the Documentation Generator.

cidl​

cidl: CIDL version
KeywordTypeOptionalityDescription
cidlSpec versionRequiredA valid CIDL specification version

info​

info: # Metadata of the smart contract
  name: smart contract name
  title: title or name of the smart contract
  version: version of the smart contract
  summary: smart contract description summary
  contact:
    name: contact name | company
    web: url of company | support
    email: email of contact | support
    git: git URL
  license:
    name: license name
    identifier: SPDX license expression
    url: license URL
KeywordTypeOptionalityDescription
infoInfoBodyRequired

Info Body​

The info object containing general information about the contract

KeywordTypeOptionalityDescription
namestringRequiredThe smart contract name. This name will be used to generate the smart contract and client libraries projects
titlestringRequiredThe title will be used to generate the web-based documentation for the smart contract
versionstringRequiredThe smart contract semantic version
summarystringRecommendedThe summary will be used to generate the web-based documentation for the smart contract. Supports markdown
contactContactBodyOptional
licenseLicenseBodyRequired
Contact Body​

The contact object defines the owner of the CIDL and its contact information

KeywordTypeOptionalityDescription
namestringRecommendedName of the CIDL maintainer
webUrlRecommendedWebsite URL of the CIDL maintainer
emailEmailRecommendedEmail of the CIDL maintainer
gitUrlRecommendedGit URL of this CIDL repository
License Body​

The license object defines the license governing this CIDL.

KeywordTypeOptionalityDescription
namestringRequiredThe license name used for the CIDL
identifierSPDXMutually exclusiveAn SPDX license expression
urlUrlMutually exclusiveA URL to the license used
info

Between identifier and url, only one is required.

Imports​

This section defines how to import external CIDL to be reused while defining a new interface. External CIDL locations can be versioned, to lock a specific version of a CIDL, or generic, pointing to the latest version ( not recommended ). To be supported in future versions.

imports​

imports: # Array external CIDLs
  - ref: name | name to be referenced inside this document.
    loc: url [ local file system, https, github ]
    solana:
      progid: pubkey | ID of the Program generated by the external CIDL
KeywordTypeOptionalityDescription
importsImportsBodyOptional

Imports Body​

The import object defines from where the CIDL is being imported

KeywordTypeOptionalityDescription
refstringRequiredReference name. Used as a prefix when an element of this CIDL is used locally. Each ref has to be unique
locstringRequiredLocation of the CIDL. The location can be: Local File System, URL (GitHub, HTTP), CIDL Hub. Locations can include a version indicator to lock the external CIDL to a stable version
solanaSolanaOptional
Solana Import Extension​

The solana import extension object defines the additional configuration for the CIDL import

KeywordTypeOptionalityDescription
progidPublicKeyRequiredThe Program ID ( as a Public Key ) of the Program generated by the imported CIDL.

Types​

This section defines new Data Structures. These structures can be referenced by methods.

types​

types:
  <type-name>: # Identifier for this Structure
    summary: type description summary
    fields: # Array of fields
      - name: field name
        type: native | extended (with some exception) data type
        description: field description
        format: The format of this field [date-time, key, etc]
        attributes: Attribute to apply to the type [max=nn, min=nn, cap=nn]
KeywordTypeOptionalityDescription
typesMap<TypeKey, TypeBody>Optional

Type Key​

Type name <type-name> must comply with the targeted programming language. The Type name is, the key to the type object map, is used to identify the data structure within the method definition. This identifier will also become the name for the smart contract data structure to be referenced within the code.

Type Body​

The type body object defines additional keywords to describe the data structure

KeywordTypeOptionalityDescription
summarystringRecommendedDocumentation summary of the data structure. Supports markdown
fieldsArray<FieldBody>RequiredAn array of fields through which we can define the properties of the data structure. At least 1 field is required.
Field Body​

The Field array field is required even if it has a single entry. Future reviews may include simple Type Definitions for single entry types

KeywordTypeOptionalityDescription
namestringRequiredThe name of the property, it must follows the targeted programming naming convention
typenative | extendedRequiredThe data type of this property
formatstringOptionalRepresents the internal format of the field. For example a String can represent a date, an email address or a url. Extended types can also be used to represent Blockchain Accounts, PublicKeys, etc.
attributesArray<string>OptionalAttributes to modify/extend the type
descriptionstringRecommendedDocumentation of the field. Supports markdown

Methods​

The Method Section describes the interface signature for each instruction exposed by the Smart Contract.

methods​

methods: # Array of methods | instructions
  - name: method name
    summary: description of this method
    solana:
      default-payer: boolean, if false disables the default fee payer. Only applicable if signers are not defined
      compress: # Array of types that should be compressed
        - type: reference to a custom-defined type
          mode: append | insert_or_append | replace_leaf | verify_leaf
    signers: # Array of signers
      - name: signer name
        type: native | extended (with some exception) data type
      - input: input name, when set, the input will be mark as a signer
    uses: # Array of string
      - import_ref.method_name
    inputs: # Array of inputs
      - name: input name
        type: [ import_ref. ] native | custom-defined type | extended
        description: short description of this input parameter
        attributes: Attribute to apply to the type [sol:init, sol:writable, cap=nn]
KeywordTypeOptionalityDescription
methodsArray<MethodBody>Required

Method Body​

KeywordTypeOptionalityDescription
namestringRequiredThe name of the method, it must follows the targeted programming naming convention
summarystringRecommendedDocumentation summary of the method. Supports markdown
solanaSolanaOptional
signersArray<SignerBody>Optional
inputsArray<InputBody>Optional
usesArray<string>OptionalList of reference methods in the form of ref.method_name, where ref is the value set in the imports
Solana Method Extension​
KeywordTypeOptionalityDescription
default-payerbooleanOptionalBy default, it is set to true. Set to false with an empty signer list to remove all signers from the method
compressArray<CompressBody>OptionalList of types to be compress.
Compress Body​
KeywordTypeOptionalityDescription
typeType | ref.TypeRequiredCan reference imported CIDLs in the form of ref.type_name, where ref is the value set in the imports
modeappend | insert_or_append | replace_leaf | verify_leafRequiredHow should this type be compress. Each mode corresponds to a method of the state compression program
Signer Body​
KeywordTypeOptionalityDescription
namestringMutually exclusiveThe name for the signing account.
typeType | ref.TypeMutually exclusiveCan reference imported CIDLs in the form of ref.type_name, where ref is the value set in the imports
inputstringMutually exclusiveReference to an input's name. It will set the input as a signer
attributesArray<string>OptionalAttributes to modify/extend the type. Only applicable when type is define
info

name/type are mutually exclusive with input. This means that name/type needs to be set or input, both cannot be defined at the same time.

Input Body​
KeywordTypeOptionalityDescription
namestringRequiredThe name of the parameter, it must follows the targeted programming naming convention
typenative | extended | Type | ref.TypeRequiredThe data type of this parameter<br /><br />Can reference imported CIDLs in the form of ref.type_name, where ref is the value set in the imports
descriptionstringRecommendedDocumentation of the input. Supports markdown
attributesArray<string>OptionalAttributes to modify/extend the type

Errors​

This section defines how to allow users to include personalized error messages associated to their business logic.

errors​

errors: # Array - Custom Errors definition
  - id: ErrorIdentifier
    msg: Error message
KeywordTypeOptionalityDescription
errorsErrorsBodyOptional
Errors Body​
KeywordTypeOptionalityDescription
idstringRequiredMust comply with the targeted programming language
msgstringRequired

Solana​

This section defines how to allow users to include Solana specific definitions

solana​

solana:
  seeds:
    <seed-name>: # Identifier for this seed definition
      bump: hardcoded bump value
      persist-bump: bump should be persisted or not
      items: # Array of seed's element, static or dynamic
        - name: literal value or variable name
          type: native or extended type, required to define dynamic seeds
KeywordTypeOptionalityDescription
solanaSolanaBodyOptional
Solana Body​
KeywordTypeOptionalityDescription
seedsMap<SeedKey, SeedBody>Optional

Seed Key​

Seed name <seed-name> must comply with the targeted programming language. The Seed name is, the key to the seed object map, is used to identify the seed definition within the method definition.

Seed Body​

The seed body object defines additional keywords to describe the seed

KeywordTypeOptionalityDescription
summarystringRecommendedDocumentation summary of the seed. Supports markdown
itemsArray<ItemBody>OptionalAn array of items through which we can define the static and dynamic seeds
Item Body​

An item that is part of the seeds array. And item can be a literal static value or a dynamic value. Dynamic value are set on runtime.

KeywordTypeOptionalityDescription
namestringRequiredA literal value or a variable for when the item is dynamic. If the item is dynamic the variable name must comply with the targeted programming language
typenative | extendedOptionalThe seed type of this property.
descriptionstringRecommendedDocumentation of the field. Supports markdown

Built-in data types​

Native​

This work in progress table describes the built-in native types supported by this specification. Translation to actual Programming Languages types will be added in followup up reviews.

Data TypeLengthAttributes
u88-bit unsigned integer
u1616-bit unsigned integer
u3232-bit unsigned integer
u6464-bit unsigned integer
u128128-bit unsigned integer
u256256-bit unsigned integer
i88-bit signed integer
i1616-bit signed integer
i3232-bit signed integer
i6464-bit signed integer
i128128-bit signed integer
i256256-bit signed integer
f3232-bit signed float
f6464-bit signed float
bool1 bit
stringDepends on the targeted blockchaincap=\d+
bytesDepends on the targeted blockchaincap=\d+

Extended​

Type extensions are custom data types. In this revision of the document, type extensions are built-in into the generator. Future revisions may add custom-made Type Extensions.

They are identified by a prefix identifier, a colon and the name of the type, i.e. prefix:identifier.

Data TypesLengthAttributesComments
arrayDepends on the targeted blockchaincap=\d+
sol:pubkey32 bytesType specific to the Solana blockchain. Transpiles to Pubkey data type.
sol:account<T?, seeds.K?>It dependssol:writable
sol:init
sol:init_if_needed
sol:close
sol:close_uncheck
sol:space=\d+
sol:owner=Pubkey
sol:address=Pubkey
sol:rent-payer=signer_name
sol:rent-receiver=input_name|signer_name		Type specific to the Solana blockchain. T is the name of a custom-defined type, it can be omitted with underscored _. K is the name of a seed definition. T and K can reference imported CIDLs in the form of ref.type_name, where ref is the value set in the imports
sol:merkle_treeIt dependssol:authority=signer_name
sol:canopy=\d+
cap=\d+		Type specific to the Solana blockchain. Transpiles to AccountInfo data type with the owner set to the account compression program.

Data type modifier​

? marks the field or input as optional/nullable. It must be added at the end of the type definition.

- name: field_name
  type: u64?

Join the Código community 💚​

Código is a growing community of developers. Join us on Discord and GitHub