orbs-contract-sdk

README

Orbs Smart Contract SDK

The Orbs smart contract SDK is a framework for building decentralized applications over the Orbs blockchain. These applications are made of smart contracts written in the Go programming language.

Note: While the Orbs smart contract SDK is stable, it is still under active development; there may be breaking changes.

Support for additional programming languages like JavaScript is under way, contact us for more information.

 

Table of contents

• Detailed documentation
• Quick start
• Deploying your first contract
• Next steps

 

Quick start

Prerequisites (Mac)

• Make sure brew is available on your machine.

• Make sure Go language 1.10+ is installed on your machine.

  Verify the installation by running in terminal go version

• To test contracts locally, make sure Docker is installed on your machine.

Installation

1. Download the Orbs smart contract SDK by running in terminal:

   go get -u github.com/orbs-network/orbs-contract-sdk/...
   

   It will be downloaded to your Go workspace, typically ~/go/src/github.com/orbs-network/orbs-contract-sdk
   Example contracts will be at ~/go/src/github.com/orbs-network/orbs-contract-sdk/go/examples

2. Install Gamma, a personal Orbs blockchain running locally, by running in terminal:

   brew install orbs-network/devtools/gamma-cli
   

   To verify the installation, run in terminal gamma-cli version

 

Deploying your first contract

1. Write a simple contract

Let's write a simple example that implements a counter. This will be our code counter.go

package main

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

var PUBLIC = sdk.Export(add, get)
var SYSTEM = sdk.Export(_init)

var COUNTER_KEY = []byte("count")

func _init() {
    state.WriteUint64(COUNTER_KEY, 0)
}

func add(amount uint64) {
    count := state.ReadUint64(COUNTER_KEY)
    count += amount
    state.WriteUint64(COUNTER_KEY, count)
}

func get() uint64 {
    return state.ReadUint64(COUNTER_KEY)
}

2. Start Gamma server

We'll test our contract on Gamma server - a locally running blockchain. Start it from terminal:

gamma-cli start-local

3. Deploy the contract

To deploy the counter contract, run in terminal:

gamma-cli deploy counter.go -name MyCounter

If the deploy is successful, you'll see a response similar to this:

{
  "RequestStatus": "COMPLETED",
  "TxId": "7Y4urVmKvunYsxh7kKhUoQ72XjSJcdkBxxzBcauC9icC9gzMy8mPDcg",
  "ExecutionResult": "SUCCESS",
  "OutputArguments": [],
  "TransactionStatus": "COMMITTED",
  "BlockHeight": "1869",
  "BlockTimestamp": "2018-12-05T13:05:51.347Z"
}

4. Send a transaction to increment the counter

Write the transaction details in a JSON file named add-25.json

{
  "ContractName": "MyCounter",
  "MethodName": "add", 
  "Arguments": [
    {
      "Type": "uint64",
      "Value": "25"
    }
  ]
}

To increment the counter by 75, let's send this transaction 3 times from terminal:

gamma-cli send-tx add-25.json -signer user1
gamma-cli send-tx add-25.json -signer user1
gamma-cli send-tx add-25.json -signer user1

Note: The transaction will be signed by user1, an example account found in orbs-test-keys.json

5. Read the counter value

Write the query details in a JSON file named get.json

{
  "ContractName": "MyCounter",
  "MethodName": "get",
  "Arguments": []
}

This query will read the counter value from the contract's state. Send it from terminal:

gamma-cli run-query get.json

Note: Transactions that change state require consensus by several nodes. Reading state with queries is a simpler action that doesn't require consensus.

6. Stop Gamma server

Since we're done testing, the server is no longer needed. Let's stop it from terminal:

gamma-cli stop-local

 

Next steps

• Explore more examples of contracts here.

• Read more about Gamma, the local Orbs blockchain, here.

  You can also run in terminal gamma-cli help

• Explore the API of the SDK here.

• After your contracts are deployed to test net or main net, build clients that access them using the Orbs Client SDK.

 

Detailed documentation

The detailed documentation website for Orbs Contract SDK is available here:

https://orbs.gitbook.io

 

License

MIT