This page is used to describe all the additional APIs which exists as part of the Contract SDK.

Env

To use the Env package, you need to import it:

import (
    "github.com/orbs-network/orbs-contract-sdk/go/sdk/v1/env"
)

It provides the following functions:

GetBlockHeight

Used to get the block height which will be the one this transaction be a part of

GetBlockHeight() uint64

It returns the block height in decimal values:

GetBlockTimestamp

Used to get the block timestamp (creation time) which will be the one this transaction be a part of:

GetBlockTimestamp() uint64

It returns the block timestamp representing the Unix epoch in nanoseconds.

GetBlockProposerAddress

Used to get the block proposer address, which is the address of the node who wrote the block or is trying to write the block right now. When called during a RunQuery operation, the address the Node that generated this block is 'read' from the block itself, this is the case where data is read from the chain and not written to it, so the block already exists. When called during a SendTransaction operation the Node that is trying to generate the block with the transaction will set its own address as block proposer.

GetBlockProposerAddress() []byte

It will return the block proposer address as a byte array

GetVirtualChainId

Used to get the virtual chain id this contract is executing on.

GetVirtualChainId() uint32

It returns the virtual chain id in decimal values.

Safemath

To use the Safemath package, you need to import it:

import (
    "github.com/orbs-network/orbs-contract-sdk/go/sdk/v1/safemath/safeuint256"
    "github.com/orbs-network/orbs-contract-sdk/go/sdk/v1/safemath/safeuint64"
    "github.com/orbs-network/orbs-contract-sdk/go/sdk/v1/safemath/safeuint32"
)

It gives the ability to work with 32, 64, and 256 bit unsigned integers in a 'safe' way meaning there is an overflow/underflow and illegal operation protection around the arithmetic operation done.

The API is uniform between the different variants and consist of the following functions:

Add

Adds two numbers and returns the result. The numbers are validated so that they do not overflow after the addition.

Add(x *big.Int, y *big.Int) *big.Int
Add(x uint32, y uint32) uint32
Add(x uint64, y uint64) uint64

Sub

Subtract y from x. The result is validated, so if it becomes negative, an error is returned.

Sub(x *big.Int, y *big.Int) *big.Int
Sub(x uint32, y uint32) uint32
Sub(x uint64, y uint64) uint64

Mul

Multiplies the values and returns the new number. The result is validated so that it does not overflow.

Mul(x *big.Int, y *big.Int) *big.Int
Mul(x uint32, y uint32) uint32
Mul(x uint64, y uint64) uint64

Div

Performs an integer division of x by y. The remainder is discarded as it should in integer arithmetic, and the input (y) is validated not to be zero.

Div(x *big.Int, y *big.Int) *big.Int
Div(x uint32, y uint32) uint32
Div(x uint64, y uint64) uint64

Mod

Performs the modulo operation of x by y. The input is validated to be valid (meaning y is not zero). The resulting number is the reminder.

Mod(x *big.Int, y *big.Int) *big.Int
Mod(x uint32, y uint32) uint32
Mod(x uint64, y uint64) uint64

Validate

The function validates that the number is not negative, and did not overflow. If the validation fails, the code panics with the appropriate message.

Validate(n *big.Int)

Note that validate is called automatically on each operation, meaning after using Add or Sub or any operation of the safemath library, so there is no need to call it manually.