NEP: NEO Executable Format (NEF)

nep-16.mediawiki

@@ -0,0 +1,106 @@
+<pre>
+  NEP: 16
+  Title: NEO Executable Format (NEF)
+  Author: Erik Zhang <erik@neo.org>, Fernando Díaz Toledano <shargon@gmail.com>, Igor Machado Coelho <igormachado@gmail.com>, Li Jianying <lightsever@hotmail.com>, Vitor Nazário Coelho <vncoelho@gmail.com>
+  Type: Standard
+  Status: Accepted
+  Created: 2020-03-31
+</pre>
+
+==Abstract==
+
+Compiled code to be executed by the Neo virtual machine is represented using a binary format, typically stored in a file, known as the <code>nef</code> file format. The <code>nef</code> file contains Neo bytecodes, as well as other ancillary information such as byte ordering and compiler used.
+
+This NEP describes the NEF standard for NEO smart contracts.
+
+==Motivation==
+
+For the sake of security, we need to place strong syntactic and structural constraints on the executable file. With the <code>nef</code> file format, we can guarantee both the validity and functionality of the compiled file.
+
+==Specification==
+
+In the field definitions below, we provide both the definitions of the fields as well as the corresponding functions.
+
+===NefFile Structure===
+
+A <code>nef</code> file consists of a stream of 8-bit bytes. Multibyte data items are always stored in little-endian order, where the low bytes come first. Its structure is described further below.
+
+<pre>
+nef_file
+{
+  4-byte  magic;
+  64-byte compiler;
+  2-byte reserve;
+  method_token{
+    20-byte hash;
+    var-byte method;
+    2-byte parametersCount;
+    1-byte hasReturnValue;
+    1-byte callFlags;
+  } tokens[];
+  2-byte reserve;
+  var-byte script;
+  4-byte checksum;
+}
+</pre>
+
+The extension name of the <code>nef</code> file should be <code>.nef</code>.
+
+====magic====
+
+The <code>magic</code> item supplies the magic number identifying the <code>NEF3</code> file format; it has the value <code>0x3346454E</code>.
+
+====compiler====
+
+The <code>compiler</code> is a UTF-8 encoded <code>string</code> representing the compiler used to create the data in the <code>script</code> item. It should indicate the name and the version of the compiler, which must be padded to make it up to the required length if shorter than 64 bytes.
+
+====reserve====
+
+All bits of the <code>reserve</code> item are reserved for future use and must be set to zero in generated nef files.
+
+====tokens====
+
+Each entry in the <code>tokens</code> item must be a <code>method_token</code> structure giving a necessary description of a method invoked by this contract.
+
+=====hash=====
+
+The <code>hash</code> item represents the hash of the static contract with the length of 20 bytes, indicating which contract the method belongs to.
+
+=====method=====
+
+The <code>method</code> item is used to represent constant string values of the method name. It has s single-byte length prefix and up to 32 byte string contents encoded in UTF-8.
+=====parametersCount=====
+
+The <code>parametersCount</code> denotes the number of formal parameters of the method.
+
+=====hasReturnValue=====
+
+The <code>hasReturnValue</code> item is a boolean value that indicates whether the method has return value or not.
+
+=====callFlags=====
+
+The value of the <code>callFlags</code> item is a mask of flags used to denote the calling permission to the method. The Interpretation of each flag, when set, is specified in the following table:
+
+{|
+!Flag Name !!Value !!Interpretation
+|-
+| None || 0 || called without other permissions
+|-
+| ReadStates || 0b00000001 || allow to read the storage 
+|-
+| WriteStates || 0b00000010 || allow to write the storage
+|-
+| AllowCall || 0b00000100 || allow to call methods in other contracts
+|-
+| AllowNotify || 0b00001000 || allow to send the notification
+|}
+
+All bits of the <code>callFlags</code> item not assigned in the table are reserved for future use. They should be set to zero in generated <code>nef</code> files.
+
+====script====
+
+The value of <code>script</code> stores the raw VM opcodes. The data should be serialised using the variable length format as described in the [https://docs.neo.org/developerguide/en/articles/conventions.html#variable-length-types documentation].
+
+====checksum====
+
+The <code>checksum</code> item is used not only to ensure a corrupt-free transmission, but also to ensure that the file has not been tampered with. It is computed by using the SHA256 algorithm to hash the serialised <code>nef</code> file excluding <code>checksum</code> twice, and converting the result into a 32-bit unsigned integer, which must be identical with the last four bytes of the <code>nef</code> file.