2021-09-06 15:40:41 +00:00
# NeoGo smart contract compiler
2018-02-19 09:24:28 +00:00
The neo-go compiler compiles Go programs to bytecode that the NEO virtual machine can understand.
2020-05-18 21:17:05 +00:00
## Language compatibility
The compiler is mostly compatible with regular Go language specification, but
there are some important deviations that you need to be aware of that make it
a dialect of Go rather than a complete port of the language:
2020-08-24 08:58:29 +00:00
* `new()` is not supported, most of the time you can substitute structs with composite literals
* `make()` is supported for maps and slices with elements of basic types
2020-08-24 09:54:01 +00:00
* `copy()` is supported only for byte slices, because of underlying `MEMCPY` opcode
2020-08-06 10:43:40 +00:00
* pointers are supported only for struct literals, one can't take an address
of an arbitrary variable
2020-05-18 21:17:05 +00:00
* there is no real distinction between different integer types, all of them
work as big.Int in Go with a limit of 256 bit in width, so you can use
`int` for just about anything. This is the way integers work in Neo VM and
adding proper Go types emulation is considered to be too costly.
* goroutines, channels and garbage collection are not supported and will
never be because emulating that aspects of Go runtime on top of Neo VM is
close to impossible
2020-08-24 06:53:52 +00:00
* `defer` and `recover` are supported except for cases where panic occurs in
`return` statement, because this complicates implementation and imposes runtime
overhead for all contracts. This can easily be mitigated by first storing values
2021-12-02 19:35:42 +00:00
in variables and returning the result. `defer` can't be used in
conditional code (#2293).
2020-08-24 06:53:52 +00:00
* lambdas are supported, but closures are not.
2020-09-29 07:56:57 +00:00
* maps are supported, but valid map keys are booleans, integers and strings with length < = 64
2020-05-18 21:17:05 +00:00
## VM API (interop layer)
2019-09-17 16:09:02 +00:00
Compiler translates interop function calls into NEO VM syscalls or (for custom
2020-05-18 21:17:05 +00:00
functions) into NEO VM instructions. [Refer to
pkg.go.dev](https://pkg.go.dev/github.com/nspcc-dev/neo-go/pkg/interop)
for full API documentation. In general it provides the same level of
functionality as Neo .net Framework library.
2018-02-19 09:24:28 +00:00
2021-09-06 15:40:41 +00:00
Compiler provides some helpful builtins in `util` , `convert` and `math` packages.
2020-09-15 13:33:34 +00:00
Refer to them for detailed documentation.
2020-10-02 10:16:02 +00:00
`_deploy()` function has a special meaning and is executed when contract is deployed.
2021-09-06 15:40:41 +00:00
It should return no value and accept two arguments: the first one is `data` containing
all values `deploy` is aware of and able to make use of; the second one is a bool
argument which will be true on contract update.
2020-10-02 10:16:02 +00:00
`_deploy()` functions are called for every imported package in the same order as `init()` .
2018-03-25 16:21:00 +00:00
## Quick start
2021-01-27 20:12:43 +00:00
### Go setup
The compiler uses Go parser internally and depends on regular Go compiler
presence, so make sure you have it installed and set up. On some distributions
this requires you to set proper `GOROOT` environment variable, like
```
2021-08-25 11:59:00 +00:00
export GOROOT=/usr/lib64/go/1.15
2021-01-27 20:12:43 +00:00
```
2022-01-20 10:28:04 +00:00
The best way to create a new contract is using `contract init` command. This will
create an example source file, config file and `go.mod` with `github.com/nspcc-dev/neo-go/pkg/interop` dependency.
```
$ ./bin/neo-go contract init --name MyAwesomeContract
$ cd MyAwesomeContract
```
You'll also need to download dependency modules for your contract like this (in the
2022-01-14 20:33:01 +00:00
directory containing contract package):
```
$ go mod tidy
```
2020-05-18 21:17:05 +00:00
### Compiling
2018-03-25 16:21:00 +00:00
```
2021-01-28 09:14:50 +00:00
./bin/neo-go contract compile -i contract.go
2018-03-25 16:21:00 +00:00
```
2021-09-06 15:40:41 +00:00
By default, the filename will be the name of your .go file with the .nef
extension, the file will be located in the same directory where your Go contract
is. If you want another location for your compiled contract:
2018-03-25 16:21:00 +00:00
```
2021-01-28 09:14:50 +00:00
./bin/neo-go contract compile -i contract.go --out /Users/foo/bar/contract.nef
2018-03-25 16:21:00 +00:00
```
2021-09-06 15:40:41 +00:00
If your contract is split across multiple files, you must provide a path
2021-01-27 20:12:43 +00:00
to the directory where package files are contained instead of a single Go file
(`out.nef` will be used as the default output file in this case):
2020-08-11 08:20:47 +00:00
```
./bin/neo-go contract compile -i ./path/to/contract
```
2020-05-18 21:17:05 +00:00
### Debugging
2018-03-25 16:21:00 +00:00
You can dump the opcodes generated by the compiler with the following command:
```
2021-01-28 09:14:50 +00:00
./bin/neo-go contract inspect -i contract.go -c
2018-03-25 16:21:00 +00:00
```
This will result in something like this:
```
2021-09-06 15:40:41 +00:00
INDEX OPCODE PARAMETER
0 INITSLOT 4 local, 2 arg < <
3 LDARG1
4 NOT
5 JMPIFNOT_L 151 (146/92000000)
10 SYSCALL System.Storage.GetContext (9bf667ce)
15 NOP
16 STLOC0
17 PUSHDATA1 53746f72616765206b6579206e6f7420796574207365742e2053657474696e6720746f2030 ("Storage key not yet set. Setting to 0")
56 CONVERT Buffer (30)
58 PUSH1
59 PACK
60 STLOC1
61 PUSHDATA1 696e666f ("info")
67 LDLOC1
68 SWAP
69 SYSCALL System.Runtime.Notify (95016f61)
74 NOP
75 PUSH0
76 STLOC2
77 LDLOC0
78 PUSHDATA1 746573742d73746f726167652d6b6579 ("test-storage-key")
96 LDLOC2
97 REVERSE3
98 SYSCALL System.Storage.Put (e63f1884)
103 NOP
104 PUSHDATA1 53746f72616765206b657920697320696e697469616c69736564 ("Storage key is initialised")
132 CONVERT Buffer (30)
134 PUSH1
135 PACK
136 STLOC3
137 PUSHDATA1 696e666f ("info")
143 LDLOC3
144 SWAP
145 SYSCALL System.Runtime.Notify (95016f61)
150 NOP
151 RET
152 INITSLOT 5 local, 0 arg
155 SYSCALL System.Storage.GetContext (9bf667ce)
160 NOP
161 STLOC0
162 LDLOC0
163 PUSHDATA1 746573742d73746f726167652d6b6579 ("test-storage-key")
181 SWAP
182 SYSCALL System.Storage.Get (925de831)
187 NOP
188 STLOC1
189 PUSHDATA1 56616c756520726561642066726f6d2073746f72616765 ("Value read from storage")
214 CONVERT Buffer (30)
216 PUSH1
217 PACK
218 STLOC2
219 PUSHDATA1 696e666f ("info")
225 LDLOC2
226 SWAP
227 SYSCALL System.Runtime.Notify (95016f61)
232 NOP
233 PUSHDATA1 53746f72616765206b657920616c7265616479207365742e20496e6372656d656e74696e672062792031 ("Storage key already set. Incrementing by 1")
277 CONVERT Buffer (30)
279 PUSH1
280 PACK
281 STLOC3
282 PUSHDATA1 696e666f ("info")
288 LDLOC3
289 SWAP
290 SYSCALL System.Runtime.Notify (95016f61)
295 NOP
296 LDLOC1
297 CONVERT Integer (21)
299 PUSH1
300 ADD
301 STLOC1
302 LDLOC0
303 PUSHDATA1 746573742d73746f726167652d6b6579 ("test-storage-key")
321 LDLOC1
322 REVERSE3
323 SYSCALL System.Storage.Put (e63f1884)
328 NOP
329 PUSHDATA1 4e65772076616c7565207772697474656e20696e746f2073746f72616765 ("New value written into storage")
361 CONVERT Buffer (30)
363 PUSH1
364 PACK
365 STLOC4
366 PUSHDATA1 696e666f ("info")
372 LDLOC4
373 SWAP
374 SYSCALL System.Runtime.Notify (95016f61)
379 NOP
380 LDLOC1
381 RET
2020-05-18 21:17:05 +00:00
```
#### Neo Smart Contract Debugger support
It's possible to debug contracts written in Go using standard [Neo Smart
Contract Debugger](https://github.com/neo-project/neo-debugger/) which is a
part of [Neo Blockchain
Toolkit](https://github.com/neo-project/neo-blockchain-toolkit/). To do that
you need to generate debug information using `--debug` option, like this:
```
2021-01-27 20:12:43 +00:00
$ ./bin/neo-go contract compile -i contract.go -c contract.yml -m contract.manifest.json -o contract.nef --debug contract.debug.json
2020-05-18 21:17:05 +00:00
```
This file can then be used by debugger and set up to work just like for any
other supported language.
### Deploying
2021-01-27 20:12:43 +00:00
Deploying a contract to blockchain with neo-go requires both NEF and JSON
manifest generated by the compiler from configuration file provided in YAML
format. To create contract manifest pass YAML file with `-c` parameter and
specify manifest output file with `-m` :
```
2021-01-28 09:14:50 +00:00
./bin/neo-go contract compile -i contract.go -c config.yml -m contract.manifest.json
2021-01-27 20:12:43 +00:00
```
2020-05-18 21:17:05 +00:00
2021-01-27 20:12:43 +00:00
Example YAML file contents:
2020-05-18 21:17:05 +00:00
```
2021-01-27 20:12:43 +00:00
name: Contract
safemethods: []
2020-11-13 18:52:42 +00:00
supportedstandards: []
events:
- name: info
parameters:
- name: message
2021-09-06 15:40:41 +00:00
type: String
2020-05-18 21:17:05 +00:00
```
2021-01-27 20:12:43 +00:00
Then the manifest can be passed to the `deploy` command via `-m` option:
2020-05-18 21:17:05 +00:00
```
2021-01-27 20:12:43 +00:00
$ ./bin/neo-go contract deploy -i contract.nef -m contract.manifest.json -r http://localhost:20331 -w wallet.json
2020-05-18 21:17:05 +00:00
```
2020-06-17 21:15:13 +00:00
Deployment works via an RPC server, an address of which is passed via `-r`
2020-05-18 21:17:05 +00:00
option and should be signed using a wallet from `-w` option. More details can
be found in `deploy` command help.
2021-07-28 10:13:55 +00:00
#### Config file
Configuration file contains following options:
| Parameter | Description | Example |
| --- | --- | --- |
| `name` | Contract name in the manifest. | `"My awesome contract"`
| `safemethods` | List of methods which don't change contract state, don't emit notifications and are available for anyone to call. | `["balanceOf", "decimals"]`
| `supportedstandards` | List of standards this contract implements. For example, `NEP-11` or `NEP-17` token standard. This will enable additional checks in compiler. The check can be disabled with `--no-standards` flag. | `["NEP-17"]`
| `events` | Notifications emitted by this contract. | See [Events ](#Events ). |
| `permissions` | Foreign calls allowed for this contract. | See [Permissions ](#Permissions ). |
2021-10-16 11:10:17 +00:00
| `overloads` | Custom method names for this contract. | See [Overloads ](#Overloads ). |
2021-07-28 10:13:55 +00:00
##### Events
Each event must have a name and 0 or more parameters. Parameters are specified using their name and type.
Both event and parameter names must be strings.
Parameter type can be one of the following:
Type in code | Type in config file
--- | ---
`bool` | `Boolean`
`int` , `int64` etc.| `Integer`
`[]byte` | `ByteArray`
`string` | `String`
Any non-byte slice `[]T` | `Array`
`map[K]V` | `Map`
`interop.Hash160` | `Hash160`
`interop.Hash256` | `Hash256`
`interop.Interface` | `InteropInterface`
`interop.PublicKey` | `PublicKey`
`interop.Signature` | `Signature`
anything else | `Any`
`interop.*` types are defined as aliases in `github.com/nspcc-dev/neo-go/pkg/interop` module
with the sole purpose of correct manifest generation.
As an example consider `Transfer` event from `NEP-17` standard:
```
- name: Transfer
parameters:
- name: from
type: Hash160
- name: to
type: Hash160
- name: amount
type: Integer
```
2021-09-06 15:40:41 +00:00
By default, compiler performs some sanity checks. Most of the time
2021-07-28 10:13:55 +00:00
it will report missing events and/or parameter type mismatch.
Using variable as an event name in code isn't prohibited but will prevent
compiler from analyzing an event. It is better to use either constant or string literal.
The check can be disabled with `--no-events` flag.
##### Permissions
Each permission specifies contracts and methods allowed for this permission.
If contract is not specified in a rule, specified set of methods can be called on any contract.
By default, no calls are allowed. Simplest permission is to allow everything:
```
- methods: '*'
```
Another common case is to allow calling `onNEP17Payment` , which is necessary
for most of the NEP-17 token implementations:
```
- methods: ["onNEP17Payment"]
```
In addition to `methods` permission can have one of these fields:
1. `hash` contains hash and restricts set of contracts to a single contract.
2. `group` contains public key and restricts set of contracts to those who
have corresponding group in their manifest.
Consider an example:
```
- methods: ["onNEP17Payment"]
- hash: fffdc93764dbaddd97c48f252a53ea4643faa3fd
methods: ["start", "stop"]
- group: 03184b018d6b2bc093e535519732b3fd3f7551c8cffaf4621dd5a0b89482ca66c9
methods: ["update"]
```
This set of permissions allows calling:
- `onNEP17Payment` method of any contract
- `start` and `stop` methods of contract with hash `fffdc93764dbaddd97c48f252a53ea4643faa3fd`
- `update` method of contract in group with public key `03184b018d6b2bc093e535519732b3fd3f7551c8cffaf4621dd5a0b89482ca66c9`
Also note, that native contract must be included here too. For example, if your contract
transfers NEO/GAS or gets some info from the `Ledger` contract, all of these
calls must be allowed in permissions.
Compiler does its best to ensure correct permissions are specified in config.
Incorrect permissions will result in runtime invocation failures.
Using either constant or literal for contract hash and method will allow compiler
to perform more extensive analysis.
This check can be disabled with `--no-permissions` flag.
2021-10-16 11:10:17 +00:00
##### Overloads
NeoVM allows a contract to have multiple methods with the same name
but different parameters number. Go lacks this feature but this can be circumvented
with `overloads` section. Essentially it is a mapping from default contract method names
to the new ones.
```
- overloads:
oldName1: newName
oldName2: newName
```
Because the use-case for this is to provide multiple implementations with the same ABI name,
`newName` is required to be already present in the compiled contract.
As an example consider [`NEP-11` standard ](https://github.com/neo-project/proposals/blob/master/nep-11.mediawiki#transfer ).
It requires divisible NFT contract to have 2 `transfer` methods. To achieve this we might implement
`Tranfer` and `TransferDivisible` and specify emitted name in config:
```
- overloads:
transferDivisible:transfer
```
2021-08-05 08:21:52 +00:00
#### Manifest file
Any contract can be included in a group identified by a public key which is used in [permissions ](#Permissions ).
This is achieved with `manifest add-group` command.
```
./bin/neo-go contract manifest add-group -n contract.nef -m contract.manifest.json --sender < sender > --wallet /path/to/wallet.json --account < account >
```
It accepts contract `.nef` and manifest files emitted by `compile` command as well as
sender and signer accounts. `--sender` is the account who will send deploy transaction later (not necessarily in wallet).
`--account` is the wallet account which signs contract hash using group private key.
2020-05-18 21:17:05 +00:00
#### Neo Express support
It's possible to deploy contracts written in Go using [Neo
Express](https://github.com/neo-project/neo-express) which is a part of [Neo
Blockchain
Toolkit](https://github.com/neo-project/neo-blockchain-toolkit/). To do that
you need to generate a different metadata file using YAML written for
deployment with neo-go. It's done in the same step with compilation via
`--config` input parameter and `--abi` output parameter, combined with debug
support the command line will look like this:
2018-03-25 16:21:00 +00:00
```
2020-06-25 16:21:49 +00:00
$ ./bin/neo-go contract compile -i contract.go --config contract.yml -o contract.nef --debug contract.debug.json --abi contract.abi.json
2020-05-18 21:17:05 +00:00
```
This file can then be used by toolkit to deploy contract the same way
contracts in other languagues are deployed.
### Invoking
You can import your contract into the standalone VM and run it there (see [VM
documentation](vm.md) for more info), but that only works for simple contracts
that don't use blockchain a lot. For more real contracts you need to deploy
them first and then do test invocations and regular invocations with `contract
testinvokefunction` and `contract invokefunction` commands (or their variants,
see `contract` command help for more details. They all work via RPC, so it's a
mandatory parameter.
2018-03-25 16:21:00 +00:00
2020-05-18 21:17:05 +00:00
Example call (contract `f84d6a337fbc3d3a201d41da99e86b479e7a2554` with method
`balanceOf` and method's parameter `AK2nJJpJr6o664CWJKi1QRXjqeic2zRp8y` using
2021-09-06 15:40:41 +00:00
given RPC server and wallet and paying 0.00001 extra GAS for this transaction):
2020-05-18 21:17:05 +00:00
```
2020-06-17 21:15:13 +00:00
$ ./bin/neo-go contract invokefunction -r http://localhost:20331 -w my_wallet.json -g 0.00001 f84d6a337fbc3d3a201d41da99e86b479e7a2554 balanceOf AK2nJJpJr6o664CWJKi1QRXjqeic2zRp8y
2020-05-18 21:17:05 +00:00
```
2019-09-17 16:09:02 +00:00
2018-02-27 09:04:24 +00:00
## Smart contract examples
2021-01-27 20:12:43 +00:00
Some examples are provided in the [examples directory ](../examples ). For more
sophisticated real-world contracts written in Go check out [NeoFS
contracts](https://github.com/nspcc-dev/neofs-contract/).
2018-02-27 09:04:24 +00:00
2018-02-24 09:06:48 +00:00
## How to report compiler bugs
2018-02-19 09:24:28 +00:00
1. Make a proper testcase (example testcases can be found in the tests folder)
2. Create an issue on Github
3. Make a PR with a reference to the created issue, containing the testcase that proves the bug
4. Either you fix the bug yourself or wait for patch that solves the problem
