Getting Started
Orbs Contracts
Gamma in Depth
Creating a new contract
Developing a contract should be done via a Golang IDE, just any other project using Go.
Development
After starting a new project/workspace, depending on the IDE, the development should start by creating the contract file, which contains the main package.
The contract file name should be meaningful. When deploying, if the contract name is not specified, we use the contract filename as the deployed contract name.
The following boilerplate can be a good start to work with:
1
package main
2
​
3
import (
4
"github.com/orbs-network/orbs-contract-sdk/go/sdk/v1"
5
"github.com/orbs-network/orbs-contract-sdk/go/sdk/v1/state"
6
)
7
​
8
var PUBLIC = sdk.Export() // TODO: add exported methods
9
var SYSTEM = sdk.Export(_init)
10
​
11
func _init() {
12
// TODO: add init logic
13
}
14
// TODO: add contract logic (methods)
Copied!
Next, add your functions and export them as needed.
Testing
Testing your contract is done by utilizing the gamma-cli, which is an emulation of the full blockchain. As part of the contract sdk we expose the following import:
1
import (
2
"github.com/orbs-network/orbs-contract-sdk/go/testing/gamma"
3
)
Copied!
It wraps the gamma-cli and enables the testing code to deploy and run functions on gamma, emulating the Orbs blockchain and ensuring your contract is behaving as expected.
We recommend creating a
test folder under the location of your contract go file and add tests there.The example below uses a standard ERC20 contract to run some tests, the folder structure is as such:
1
/
2
- /test
3
- - /balanceOf_user1.json
4
- - /token_init_test.go
5
- /erc20.go
Copied!
In that folder structure,
erc20.go is the contract implementation, token_init_test.go holds some testing code which we explore later, and balanceOfuser1.json holds the gamma-cli query payload, which is executed over the Orbs blockchain (gamma) and runs the test.Observing the testing code,
token_init_test.go we can see the following:token_init_test.go
1
package test
2
​
3
import (
4
"github.com/orbs-network/orbs-contract-sdk/go/testing/gamma"
5
"strings"
6
"testing"
7
)
8
​
9
func TestTokenInit(t *testing.T) {
10
gammaCli := gamma.Cli().Start()
11
defer gammaCli.Stop()
12
​
13
out := gammaCli.Run("deploy ../erc20.go -name OrbsERC20 -signer user1")
14
if !strings.Contains(out, `"ExecutionResult": "SUCCESS"`) {
15
t.Fatal("deploy failed")
16
}
17
​
18
if !strings.Contains(out, `"EventName": "Transfer",`) {
19
t.Fatal("initial transfer (mint) did not fire during init")
20
}
21
​
22
out = gammaCli.Run("run-query balanceOf-user1.json")
23
if !strings.Contains(out, `"Value": "1000000000000000"`) {
24
t.Fatal("initial get failed")
25
}
26
}
Copied!
We can see that it uses the
gamma package, which is the wrapping of gamma-cli inside go code. Using Start() tells it to run gamma and wait for it to start, which can take several seconds to complete.Next, the test itself tried to deploy the contract, the command to deploy inside the
Run() function is exactly the same as you would execute from within the command line, as this is wrapping gamma execution directly.The testing code then asserts for two things:
- If the execution of the deploy was successful
- Then if there was a
Transferevent, as the ERC20 implementation performs a transfer in its_init()function, and the ERC20 spec requires an event on transfer
Next, a query is executed to assert that the balance of
user1 is as expected. This is more of a sanity check on the deploy, to make sure that indeed the blockchain was updated correctly and that the contract initiated everything as expected. The payload inside balanceOf_user1.json is:1
{
2
"ContractName": "OrbsERC20",
3
"MethodName": "balanceOf",
4
"Arguments": [
5
{
6
"Type": "gamma:keys-file-address",
7
"Value": "user1"
8
}
9
]
10
}
Copied!
Which means that the method
balanceOf in contract OrbsERC20 is executed with the argument specified, which is the key for user1 (the user which was used to sign the deploy transaction)Copy link