Update command-reference.md

docs/Neo Express Invocation File.md

@@ -0,0 +1,113 @@
+<!-- markdownlint-enable -->
+# Neo Express Contract Invocation File
+
+## Overview
+
+Neo Express uses a JSON file containing contract invocation information, which can be passed by path to the `contract invoke` neo-express command. 
+
+This document describes the initial format of Neo contract invoke files used by Neo Express V3.0 and later versions .
+
+There are several advantages of using a invoke file instead of the command line:
+
+- invoke files can be checked into source control
+- invoke files can handle arbitrarily complex sets of arguments, including UTXO information
+- invoke files can be generated by tools such as Visual DevTracker
+
+## Invocation File Format
+
+A neo-invoke file is a serialized JSON object that contains the information needed
+to invoke a Neo smart contract. The file can have any extension, though it typically
+uses `.neo-invoke.json` to both indicate its usage as well as enable JSON syntax
+highlighting in tools.
+
+A neo-invoke JSON object has three properties: `contract`, `operation` and `args`.
+
+### `contract` Property
+
+The `contract` property contains information about what contract to invoke. This
+property is a JSON object with one of two mutually exclusive properties:
+
+- `hash` is the hex-encoded script hash of the contract to invoke. The format expected
+  matches the top level `hash` property of the .abi.json file generated by the [NEON compiler](https://github.com/neo-project/neo-devpack-dotnet).
+- `path` is an absolute or relative path to the compiled contract binary (.nef). The script hash of the contract will be calculated at run time by neo-express.
+
+### `operation` Property
+
+For invoking N3 contracts, the operation must be specified by name in the invocation file.
+
+### `args` Property
+
+The `args` property contains an array of contract parameters to be passed to the contact via the invoke script. neo-express generates the invoke script for the contract specified via the `contract` and  `operation` property.
+
+The following JSON types are treated as the corresponding Contract parameter type:
+
+- Boolean
+- Integer
+  - Note, non-integer JSON numbers are not valid contract parameters. Additionally,
+    only integers that fall between [`Number.MIN_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER) and [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)
+    can be encoded in this manner. Integers that fall outside that range should be
+    encoded using the type/value approach detailed above.
+- String
+- Array
+
+Additionally, direct encoded strings can use special prefixes to indicate other contract
+parameter types:
+
+- Direct encoded strings with a '@' prefix are treated as a wallet address. Available inputs are:
+
+  - @+wallet name - the default address in the wallet will be read and converted to Uint160 as the contract parameter
+  - @+address - the Base58 encoded address will be converted to Uint160 as the contract parameter
+
+  For example:
+
+  @genesis 
+
+  @node1
+
+  @NZg1gGbZ4VrAFnjmxLxWn2MHbsBXM2s8hY
+
+- Direct encoded strings with a '#' prefix are treated as a contract hash. Available inputs are:
+
+  - #+script hash - the script hash will be converted into Uint160 as the contract parameter
+  - #+transaction hash - the transaction hash will be converted into Uint256 as the contract parameter
+  - #+block hash - the block hash will be converted into Uint256 as the contract parameter
+  - #+contract name - the corresponding contract will be queried and related contract hash will be converted into Uint160 as the contract parameter
+
+  For example:
+
+  #0x558a35116215a65a03eeb156704f34a07404ee96
+
+  #0xc401a47c96711a6cf99cc2cbc185c249a935dab0df43bf6886093eacec2010b2
+
+  #neo
+
+  #test-contract 
+
+## Example
+
+Following is an example of invocation file:
+
+``` json
+[
+    {
+        "contract": "token",
+        "operation": "transfer",
+        "args": [
+            "@dev",
+            "@genesis",
+            1000,
+            []
+        ]
+    },
+    {
+        "contract": "token",
+        "operation": "transfer",
+        "args": [
+            "@dev",
+            "#NFT",
+            1000,
+            []
+        ]
+    }
+]
+```