From f4cbabeba0729e69d6f1306a8cb663a56768ea07 Mon Sep 17 00:00:00 2001 From: Erik Zhang Date: Wed, 13 Sep 2017 19:17:05 +0800 Subject: [PATCH 1/6] draft --- NeoContractABI.mediawiki | 137 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 NeoContractABI.mediawiki diff --git a/NeoContractABI.mediawiki b/NeoContractABI.mediawiki new file mode 100644 index 00000000..f3313309 --- /dev/null +++ b/NeoContractABI.mediawiki @@ -0,0 +1,137 @@ +
+  NEP: 
+  Title: NeoContract ABI
+  Author: Erik Zhang 
+  Type: Standard
+  Status: Draft
+  Created: 2017-9-13
+
+ +==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 object which describes the details of each function in the contract. + +events is an array of Event object which describes the details of each event in the contract. + +===Function=== + +Function object has the following structure: + +
+{
+  "name": "transfer",
+  "paramaters": [],
+  "returntype": "Boolean"
+}
+
+ +name is the name of the function, which can be any valid identifier. + +paramaters is an array of Paramater object which describes the details of each paramater 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",
+  "paramaters": []
+}
+
+ +name is the name of the event, which can be any valid identifier. + +paramaters is an array of Paramater object which describes the details of each paramater in the event. + +===Paramater=== + +Paramater object has the following structure: + +
+{
+  "name": "from",
+  "type": "Hash160"
+}
+
+ +name is the name of the paramater, which can be any valid identifier. + +type indicates the type of the paramater. It can be one of the following values: Signature, Boolean, Integer, Hash160, Hash256, ByteArray, PublicKey, String, Array, InteropInterface. + +===ParamaterType=== + +ParamaterType enum has the following values: + +{| +!name +!description +|- +| Signature +| A signature of transaction or block which is generated by 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. +|- +| 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. +|} From f89269c9488d26db4cbdf756280b61858e28b1a5 Mon Sep 17 00:00:00 2001 From: Erik Zhang Date: Wed, 13 Sep 2017 23:18:11 +0800 Subject: [PATCH 2/6] fix spelling --- NeoContractABI.mediawiki | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/NeoContractABI.mediawiki b/NeoContractABI.mediawiki index f3313309..69234158 100644 --- a/NeoContractABI.mediawiki +++ b/NeoContractABI.mediawiki @@ -4,12 +4,12 @@ Author: Erik Zhang Type: Standard Status: Draft - Created: 2017-9-13 + Created: 2017-09-13 ==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. +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. @@ -42,9 +42,9 @@ The NeoContract ABI is defined by JSON format, which has the following basic str entrypoint indicates that which is the entry point of the contract in functions. -functions is an array of Function object which describes the details of each function in the contract. +functions is an array of Function objects which describe the details of each function in the contract. -events is an array of Event object which describes the details of each event in the contract. +events is an array of Event objects which describe the details of each event in the contract. ===Function=== @@ -53,14 +53,14 @@ Function object has the following structure: 
 {
   "name": "transfer",
-  "paramaters": [],
+  "parameters": [],
   "returntype": "Boolean"
 }
name is the name of the function, which can be any valid identifier. -paramaters is an array of Paramater object which describes the details of each paramater in the function. +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. @@ -71,17 +71,17 @@ Event object has the following structure: 
 {
   "name": "refund",
-  "paramaters": []
+  "parameters": []
 }
name is the name of the event, which can be any valid identifier. -paramaters is an array of Paramater object which describes the details of each paramater in the event. +parameters is an array of Parameter objects which describe the details of each parameter in the event. -===Paramater=== +===Parameter=== -Paramater object has the following structure: +Parameter object has the following structure: 
 {
@@ -90,20 +90,20 @@ Paramater object has the following structure:
 }
-name is the name of the paramater, which can be any valid identifier. +name is the name of the parameter, which can be any valid identifier. -type indicates the type of the paramater. It can be one of the following values: Signature, Boolean, Integer, Hash160, Hash256, ByteArray, PublicKey, String, Array, InteropInterface. +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. -===ParamaterType=== +===ParameterType=== -ParamaterType enum has the following values: +ParameterType enum has the following values: {| !name !description |- | Signature -| A signature of transaction or block which is generated by user. +| A signature of a transaction or block which is generated by the user. |- | Boolean | A boolean value can be either true or false. From 14438b7882daefe946b247bd8f20e9a6b63490a7 Mon Sep 17 00:00:00 2001 From: Erik Zhang Date: Thu, 14 Sep 2017 09:52:34 +0800 Subject: [PATCH 3/6] update status for accepting NEP-3 --- NeoContractABI.mediawiki => nep-3.mediawiki | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename NeoContractABI.mediawiki => nep-3.mediawiki (99%) diff --git a/NeoContractABI.mediawiki b/nep-3.mediawiki similarity index 99% rename from NeoContractABI.mediawiki rename to nep-3.mediawiki index 69234158..e31a95d2 100644 --- a/NeoContractABI.mediawiki +++ b/nep-3.mediawiki @@ -1,9 +1,9 @@ 
-  NEP: 
+  NEP: 3
   Title: NeoContract ABI
   Author: Erik Zhang 
   Type: Standard
-  Status: Draft
+  Status: Accepted
   Created: 2017-09-13
From c5df0bdf7c73e8a4a76dd56a73a6de3059da2b1d Mon Sep 17 00:00:00 2001 From: Erik Zhang Date: Sun, 1 Oct 2017 08:58:00 +0800 Subject: [PATCH 4/6] add recommended entry point --- nep-3.mediawiki | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/nep-3.mediawiki b/nep-3.mediawiki index e31a95d2..0d84771b 100644 --- a/nep-3.mediawiki +++ b/nep-3.mediawiki @@ -127,7 +127,7 @@ ParameterType enum has the following values: | A string which is encoded in UTF-8. |- | Array -| An array of objects. +| An array of objects. The type of elements can be any value of ParameterType. |- | InteropInterface | An interface which is returned by interop services. @@ -135,3 +135,26 @@ ParameterType enum has the following values: | 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 invoke with the first parameter, and specifying the parameters of the function with the second argument. From 748db7599fa9e342c8f1d41e8f0767c56dad261e Mon Sep 17 00:00:00 2001 From: Erik Zhang Date: Fri, 13 Oct 2017 15:55:36 +0800 Subject: [PATCH 5/6] Update nep-3.mediawiki --- nep-3.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nep-3.mediawiki b/nep-3.mediawiki index 0d84771b..4ca33fb9 100644 --- a/nep-3.mediawiki +++ b/nep-3.mediawiki @@ -157,4 +157,4 @@ It is strongly recommended that each contract have the following entry point fun } -In this way, the caller can easily access the functions through the entry point, specifying the name of the function to invoke with the first parameter, and specifying the parameters of the function with the second argument. +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. From f01bf49f3d8a64406fbbbcb2ea11c8ad43b6e61a Mon Sep 17 00:00:00 2001 From: Erik Zhang Date: Wed, 20 Dec 2017 16:22:29 +0800 Subject: [PATCH 6/6] change state to final --- README.mediawiki | 4 ++-- nep-3.mediawiki | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.mediawiki b/README.mediawiki index 9417cc8b..adcb254f 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -27,11 +27,11 @@ First review [[nep-1.mediawiki|NEP-1]]. Then clone the repository and add your N | Standard | Final |- -| [https://github.com/neo-project/proposals/pull/12 3] +| [[nep-3.mediawiki|3]] | NeoContract ABI | Erik Zhang | Standard -| Accepted +| Final |- | [[nep-4.mediawiki|4]] | Dynamic Contract Invocation diff --git a/nep-3.mediawiki b/nep-3.mediawiki index 4ca33fb9..d7a05bdd 100644 --- a/nep-3.mediawiki +++ b/nep-3.mediawiki @@ -3,7 +3,7 @@ Title: NeoContract ABI Author: Erik Zhang Type: Standard - Status: Accepted + Status: Final Created: 2017-09-13