Skip to content

Latest commit

 

History

History
160 lines (121 loc) · 4.89 KB

nep-3.mediawiki

File metadata and controls

160 lines (121 loc) · 4.89 KB
Raw

  NEP: 3
  Title: NeoContract ABI
  Author: Erik Zhang <[email protected]>
  Type: Standard
  Status: Final
  Created: 2017-09-13

Table of Contents

Abstract

An Application Binary Interface (ABI) is the interface between two program modules, one of which is often a library and/or operating system and the other one is usually an application created by a regular programmer.

This NEP describes the ABI standards for NEO smart contracts.

Motivation

NEO smart contract system is designed to be mutually invocable between contracts. To achieve this, we need a mechanism for exposing the interface of smart contracts. With NeoContract ABI, developers can easily create programs to invoke smart contracts or write clients that automatically access contract functionalities.

Rationale

We assume the Application Binary Interface (ABI) is strongly typed, known at compilation time and static. No introspection mechanism will be provided. We assert that all contracts will have the interface definitions of any contracts they call available at compile-time.

This specification does not address contracts whose interface is dynamic or otherwise known only at run-time. Should these cases become important they can be adequately handled as facilities built within the NEO ecosystem.

Specification

Contract

The NeoContract ABI is defined by JSON format, which has the following basic structure, where some of the top-level objects can have any number of child objects: 

{
  "hash": "0x562851057d8afbc08fabc8c438d7cc771aef2195",
  "entrypoint": "main",
  "functions": [],
  "events": []
}

hash is the script hash of the contract. It is encoded as a hexadecimal string in big-endian.

entrypoint indicates that which is the entry point of the contract in functions.

functions is an array of Function objects which describe the details of each function in the contract.

events is an array of Event objects which describe the details of each event in the contract.

Function

Function object has the following structure: 

{
  "name": "transfer",
  "parameters": [],
  "returntype": "Boolean"
}

name is the name of the function, which can be any valid identifier.

parameters is an array of Parameter objects which describe the details of each parameter in the function.

returntype indicates the return type of the function. It can be one of the following values: Signature, Boolean, Integer, Hash160, Hash256, ByteArray, PublicKey, String, Array, InteropInterface, Void.

Event

Event object has the following structure: 

{
  "name": "refund",
  "parameters": []
}

name is the name of the event, which can be any valid identifier.

parameters is an array of Parameter objects which describe the details of each parameter in the event.

Parameter

Parameter object has the following structure: 

{
  "name": "from",
  "type": "Hash160"
}

name is the name of the parameter, which can be any valid identifier.

type indicates the type of the parameter. It can be one of the following values: Signature, Boolean, Integer, Hash160, Hash256, ByteArray, PublicKey, String, Array, InteropInterface.

ParameterType

ParameterType enum has the following values:

name description
Signature A signature of a transaction or block which is generated by the user.
Boolean A boolean value can be either true or false.
Integer An arbitrarily large integer whose value in theory has no upper or lower bounds.
Hash160 A 160-bits integer.
Hash256 A 256-bits integer.
ByteArray A byte array.
PublicKey An ECC public key which is encoded with compressed mode.
String A string which is encoded in UTF-8.
Array An array of objects. The type of elements can be any value of ParameterType.
InteropInterface An interface which is returned by interop services.
Void Void means that the function has no return value. This value cannot be the type of a parameter.

EntryPoint

It is strongly recommended that each contract have the following entry point function: 

{
  "name": "main",
  "parameters": [
    {
      "name": "operation",
      "type": "String"
    },
    {
      "name": "args",
      "type": "Array"
    }
  ],
  "returntype": "ByteArray"
}

In this way, the caller can easily access the functions through the entry point, specifying the name of the function to be invoked with the first parameter, and specifying the parameters of the function with the second parameter.