SDK

The VSC SDK is a library that abstract away various functionalities that are useful in the context of writing a VSC smart contract.

Nice To Know

They also serve access to the smart contract’s database layer by exposing namespaces and interfaces. At the stage of the contract execution, invocations of such interfaces are translated to generalized calls of the VSC node. Thereby ensuring that those functionalities are equal regardless of the language implementation of the SDK.

Go Contract SDK

The Go contract SDK implements the necessary runtime and SDK functions for the VSC smart contract environment.

Example Usage

package main

import (
  "contract-template/sdk"
)

//go:wasmexport entrypoint
func Entrypoint(a *string) *string {
  sdk.Log(*a)
  sdk.Log("Entrypoint logged")
  return a
}

SDK Methods

The below methods are within the sdk namespace. All parameters and return types are *string.

Log

Log a string for debugging purposes. Logs emitted will also be appended to the contract output which may be useful for external applications (i.e. indexers).

//go:wasmexport entrypoint
func Entrypoint(a *string) *string {
  // ...
  sdk.Log(*a)
  sdk.Log("hello world")
  // ...
}

SetObject

Set the value of a key in the contract database.

//go:wasmexport setString
func SetString(a *string) *string {
  // ...
  sdk.StateSetObject("myString", *a)
  // ...
}

GetObject

Retrieve the value of a key from the contract database.

//go:wasmexport getString
func GetString(a *string) *string {
  // ...
  value := sdk.StateGetObject("myString")
  // ...
}

DelObject

Delete the value of a key in the contract database.

//go:wasmexport clearString
func ClearString(a *string) *string {
  // ...
  sdk.StateDeleteObject("myString")
  // ...
}

GetEnv

Retrieve the current runtime environment variables, returning an object of Env struct.

//go:wasmexport dumpEnv
func DumpEnv(a *string) *string {
  // ...
  envs := sdk.GetEnv()
  // ...
}

GetEnvKey

Retrieve an environment variable by key. List of variable names are listed below.

//go:wasmexport dumpEnvKey
func DumpEnvKey(a *string) *string {
  // ...
  contract_id := sdk.GetEnvKey("contract.id")
  // ...
}

GetBalance

Retrieve the balance of any VSC account or contract.

//go:wasmexport getBalance
func GetBalance(a *string) *string {
  // ...
  bal := sdk.GetBalance("hive:vaultec.vsc", sdk.AssetHive)   // result in terms of mHIVE/mHBD
  // ...
}

Draw

Transfer assets from caller account to the contract up to the limit specified in intents. The transaction must be signed using active authority for Hive accounts.

//go:wasmexport drawBalance
func DrawBalance(a *string) *string {
  // ...
  sdk.HiveDraw(1000, sdk.AssetHive) // Draw 1 HIVE from caller
  // ...
}

Transfer

Transfer assets from the contract to another account.

//go:wasmexport transferBalance
func TransferBalance(a *string) *string {
  // ...
  sdk.HiveTransfer("hive:vaultec.vsc", 1000, sdk.AssetHive) // Transfer 1 HIVE from contract
  // ...
}

Withdraw

Unmap assets from the contract to a specified Hive account.

//go:wasmexport unmapBalance
func UnmapBalance(a *string) *string {
  // ...
  sdk.HiveWithdraw("hive:vaultec.vsc", 1000, sdk.AssetHive) // Withdraw 1 HIVE from contract
  // ...
}

Abort

Abort contract execution and revert transaction.

//go:wasmexport abortMe
func AbortMe(a *string) *string {
  // ...
  sdk.Abort("something went wrong")
  // ...
}

Revert

Abort contract execution and revert transaction in the same way as sdk.Abort() but with error symbol.

//go:wasmexport revertMe
func RevertMe(a *string) *string {
  // ...
  sdk.Revert("something went wrong", "some_error_code")
  // ...
}

Env Vars

• contract.id: ID of the current contract
• tx.id: ID of the transaction
• tx.index: Transaction position in block
• tx.op_index: Operation position in transaction
• block.id: L1 block ID in which the transaction is included in. For offchain transactions, this refers to the L1 block ID of the VSC block in which the transaction was included in.
• block.height: L1 block number in which the transaction is included in. For offchain transactions, this refers to the L1 block number of the VSC block in which the transaction was included in.
• block.timestamp: Timestamp of when the transaction was included in (i.e. 2025-07-26T14:10:42).
• msg.sender: Address of the transaction sender. This must be a user address. If there are multiple, the first account specified in required_auths or required_posting_auths is returned.
• msg.required_auths: The required_auths field of the transaction.
• msg.required_posting_auths: The required_posting_auths field of the transaction.
• msg.caller: The address that is calling the contract. It can be a contract ID or user address.
• intents: List of intents passed into the transaction (i.e. token allowance).

Contract Test Utils

The contract test utils provides a testing environment that lets you execute your contracts.

Instantiation

Create a new contract test environment.

import (
  "encoding/json"
  "testing"

  "github.com/stretchr/testify/assert"
  "github.com/vsc-eco/go-vsc-node/lib/test_utils"
  "github.com/vsc-eco/go-vsc-node/modules/db/vsc/contracts"
  ledgerDb "github.com/vsc-eco/go-vsc-node/modules/db/vsc/ledger"
  stateEngine "github.com/vsc-eco/go-vsc-node/modules/state-processing"
)

func TestContract(t *testing.T) {
  ct := test_utils.NewContractTest()
}

Increment Blocks

Increment a specified number of L1 blocks in the contract testing environment. The block height starts from 0 during instantiation.

func TestContract(t *testing.T) {
  // ...
  ct.IncrementBlocks(20)
  // ...
}

Register Contract

Bind a WASM bytecode to a contract ID.

//go:embed artifacts/main.wasm
var ContractWasm []byte

func TestContract(t *testing.T) {
  // ...
  ct.RegisterContract("vsccontractid", ContractWasm)
  // ...
}

Call Contract

Executes a contract call transaction. Returns the call result, gas used and logs emitted.

func TestContract(t *testing.T) {
  // ...
  result, gasUsed, logs := ct.Call(stateEngine.TxVscCallContract{
      Self: stateEngine.TxSelf{
      TxId:                 "sometxid",
      BlockId:              "abcdef",
      Index:                69,
      OpIndex:              0,
      Timestamp:            "2025-09-03T00:00:00",
      RequiredAuths:        []string{"hive:someone"},
      RequiredPostingAuths: []string{},
    },
    ContractId: contractId,
    Action:     "yourMethodName",
    Payload:    json.RawMessage([]byte("1000")),
    RcLimit:    1000,
    Intents:    []contracts.Intent{{
      Type: "transfer.allow",
      Args: map[string]string{
        "limit": "1.000",
        "token": "hive",
      },
    }},
  })
  assert.True(t, result.Success)
  assert.LessOrEqual(t, gasUsed, uint(10000000))
  assert.GreaterOrEqual(t, len(logs), 1)
  // ...
}

Deposit

Add funds to an account in the ledger.

func TestContract(t *testing.T) {
  // ...
  ct.Deposit("hive:someone", 1000, ledgerDb.AssetHive) // deposit 1 HIVE
  ct.Deposit("hive:someone", 1000, ledgerDb.AssetHbd) // deposit 1 HBD
  // ...
}

Get Balance

Retrieve the current balance of an account.

func TestContract(t *testing.T) {
  // ...
  bal := ct.GetBalance("hive:someone", ledgerDb.AssetHive)
  assert.Equal(t, int64(1000), bal)
  // ...
}

State Set

Set the value of a key in the contract state storage.

func TestContract(t *testing.T) {
  // ...
  ct.StateSet("vsccontractid", "someKey", "hi")
  // ...
}

State Get

Retrieve the value of a key from the contract state storage.

func TestContract(t *testing.T) {
  // ...
  val := ct.StateGet("vsccontractid", "someKey")
  assert.Equal(t, "hi", val)
  // ...
}

State Delete

Unset the value of a key in the contract state storage.

func TestContract(t *testing.T) {
  // ...
  ct.StateDelete("vsccontractid", "someKey")
  assert.Equal(t, "", ct.StateGet("vsccontractid", "someKey"))
  // ...
}