Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

NEP: NeoContract ABI #119

Merged
merged 8 commits into from
Jul 29, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.mediawiki
Original file line number Diff line number Diff line change
Expand Up @@ -57,11 +57,11 @@ First review [[nep-1.mediawiki|NEP-1]]. Then clone the repository and add your N
| Standard
| Accepted
|-
| [https://github.com/neo-project/proposals/pull/119 14]
| [[nep-14.mediawiki|14]]
| NeoContract ABI
| Erik Zhang
| Standard
| Accepted
| Final
|-
| [https://github.com/neo-project/proposals/pull/114 15]
| NeoContract Manifest
Expand Down
144 changes: 144 additions & 0 deletions nep-14.mediawiki
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
<pre>
NEP: 14
Title: NeoContract ABI
Author: Erik Zhang <erik@neo.org>
Type: Standard
Status: Final
Created: 2020-03-25
Replaces: 3
</pre>

==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:

<pre>
{
"methods": [],
"events": []
}
</pre>

<code>methods</code> is an array of Method objects which describe the details of each method in the contract.

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

===Method===

Method object has the following structure:

<pre>
{
"name": "transfer",
"offset": 0,
"safe": false,
"parameters": [],
"returntype": "Boolean"
}
</pre>

<code>name</code> is the name of the method, which can be any valid identifier.

<code>offset</code> is the offset of this method in the script.

<code>safe</code> indicates if it's safe to call this method. If a method is marked as safe, the user interface will not give any warnings when it is called by any other contract.

<code>parameters</code> is an array of Parameter objects which describe the details of each parameter in the method.

<code>returntype</code> indicates the return type of the method. It can be one of the following values: <code>Any</code>, <code>Signature</code>, <code>Boolean</code>, <code>Integer</code>, <code>Hash160</code>, <code>Hash256</code>, <code>ByteArray</code>, <code>PublicKey</code>, <code>String</code>, <code>Array</code>, <code>Map</code>, <code>InteropInterface</code>, <code>Void</code>.

===Event===

Event object has the following structure:

<pre>
{
"name": "refund",
"parameters": []
}
</pre>

<code>name</code> is the name of the event, which can be any valid identifier.

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

===Parameter===

Parameter object has the following structure:

<pre>
{
"name": "from",
"type": "Hash160"
}
</pre>

<code>name</code> is the name of the parameter, which can be any valid identifier.

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

===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 <code>true</code> or <code>false</code>.
|-
| 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.
|-
| Map
| A map of objects. The type of elements inside the key/value collection can be any value of ParameterType.
|-
| InteropInterface
| An interface which is returned by interop services.
|-
| Any
| Any means that the method will return a value of uncertain type.
|-
| Void
| Void means that the method has no return value. This value cannot be the type of a parameter.
|}