SDK Reference
Go SDK
Pre-launch
Section
SDK Reference
Documentation category
Type
Guide
Technical reference
Summary
Complete reference for the SwssChain Go SDK including module setup, client configuration, transaction submission, contract interaction, and concurrency patterns.
SWSS Foundation Notice

This documentation is restricted to authorised members of the SWSS Developer Community. Access is granted exclusively through SWSS DevHub, after KYB and SWSS Foundation approval.

All SwssChain GitHub repositories are private. Significant updates are currently deploying across the full SWSS Ecosystem. SDK and API specifications are subject to change at any time in accordance with security requirements and SwssChain Foundation governance decisions.

Join SWSS DevHub →Have a question? Use the Need Help? button below.
SDK Update Notice

SWSS SDK v2.1 is deploying across the ecosystem. API signatures may change during this period. Ensure your integration uses the latest schema from SWSS DevHub.

Article Content

Go SDK

The SwssChain Go SDK (github.com/swsschain/go-sdk) provides a type-safe, idiomatic Go interface to the SwssChain network. It uses the standard context package for cancellation and timeout propagation, exposes all operations as explicit error returns, and supports concurrent usage via goroutines.

Installation

go get github.com/swsschain/go-sdk@latest

Minimum Go version: 1.21. The module uses generics (Go 1.18+) and context-aware I/O throughout.

Module Initialisation

module myapp

go 1.21

require github.com/swsschain/go-sdk v1.3.0

Client Setup

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    swss "github.com/swsschain/go-sdk"
)

func main() {
    client, err := swss.NewClient(&swss.Config{
        Network:    swss.Mainnet,     // or swss.Testnet
        PrivateKey: os.Getenv("PRIVATE_KEY"),
        // Optional overrides
        RPCURL:  os.Getenv("SWSSCHAIN_RPC_URL"),
        WSURL:   os.Getenv("SWSSCHAIN_WS_URL"),
        Timeout: 30, // seconds
    })
    if err != nil {
        log.Fatalf("failed to create client: %v", err)
    }
    defer client.Close()

    ctx := context.Background()
    block, err := client.GetBlockNumber(ctx)
    if err != nil {
        log.Fatalf("failed to get block: %v", err)
    }
    fmt.Printf("Current block: %d\n", block)
}

Reading Chain State

ctx := context.Background()

// Block number
blockNum, err := client.GetBlockNumber(ctx)
if err != nil {
    return fmt.Errorf("get block number: %w", err)
}

// Block details
block, err := client.GetBlock(ctx, blockNum)
if err != nil {
    return fmt.Errorf("get block: %w", err)
}
fmt.Printf("Hash: %s | Txs: %d\n", block.Hash, len(block.Transactions))

// Balance
balance, err := client.GetBalance(ctx, "0xYourAddress")
if err != nil {
    return fmt.Errorf("get balance: %w", err)
}
fmt.Printf("Balance: %s SWSS\n", swss.FormatSWSSCoin(balance))

// Transaction receipt
receipt, err := client.GetTransactionReceipt(ctx, "0xTxHash")
if err != nil {
    return fmt.Errorf("get receipt: %w", err)
}
fmt.Printf("Status: %s | Block: %d\n", receipt.Status, receipt.BlockNumber)

Sending Transactions

ctx := context.Background()

// Parse SWSS Coin amount
amount, err := swss.ParseSWSSCoin("2.5")
if err != nil {
    return fmt.Errorf("parse amount: %w", err)
}

// Submit transaction
txHash, err := client.SendTransaction(ctx, &swss.TransactionRequest{
    To:    "0xRecipientAddress",
    Value: amount,
    // Gas is estimated automatically if omitted
})
if err != nil {
    return fmt.Errorf("send transaction: %w", err)
}
fmt.Printf("Submitted: %s\n", txHash)

// Wait for confirmation with context timeout
waitCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

receipt, err := client.WaitForTransaction(waitCtx, txHash, &swss.WaitOptions{
    Confirmations: 2,
})
if err != nil {
    return fmt.Errorf("wait for transaction: %w", err)
}
fmt.Printf("Confirmed in block %d\n", receipt.BlockNumber)

Contract Interaction

package main

import (
    "context"
    "fmt"
    "log"
    "math/big"

    swss "github.com/swsschain/go-sdk"
    "github.com/swsschain/go-sdk/abi"
)

// ERC-20 compatible ABI (abbreviated)
const erc20ABI = `[
    {"name":"balanceOf","type":"function","stateMutability":"view",
     "inputs":[{"name":"account","type":"address"}],
     "outputs":[{"name":"","type":"uint256"}]},
    {"name":"transfer","type":"function",
     "inputs":[{"name":"to","type":"address"},{"name":"amount","type":"uint256"}],
     "outputs":[{"name":"","type":"bool"}]}
]`

func main() {
    client, _ := swss.NewClient(&swss.Config{Network: swss.Mainnet})
    defer client.Close()

    parsedABI, err := abi.Parse(erc20ABI)
    if err != nil {
        log.Fatal(err)
    }

    contract := client.GetContract("0xContractAddress", parsedABI)
    ctx := context.Background()

    // Read call
    result, err := contract.Call(ctx, "balanceOf", "0xHolderAddress")
    if err != nil {
        log.Fatal(err)
    }
    balance := result[0].(*big.Int)
    fmt.Printf("Balance: %s\n", balance.String())

    // Write call
    txHash, err := contract.Send(ctx, "transfer",
        "0xRecipientAddress",
        new(big.Int).Exp(big.NewInt(10), big.NewInt(18), nil), // 1 token
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Transfer tx: %s\n", txHash)
}

Deed Settlement

ctx := context.Background()

amount, _ := swss.ParseSWSSCoin("250000")

settlement, err := client.Deed.Submit(ctx, &swss.DeedSubmission{
    Type:            swss.DeedTypeHomeDeed,
    PropertyID:      "PROP-2025-00142",
    ParcelRef:       "SG-00142-A",
    SettlementValue: amount,
    FromAddress:     "0xSellerAddress",
    ToAddress:       "0xBuyerAddress",
    Metadata: map[string]string{
        "jurisdiction":       "SG",
        "registration_ref":  "REF-2025-00142",
    },
})
if err != nil {
    return fmt.Errorf("deed submission: %w", err)
}

fmt.Printf("Settlement ID: %s\n", settlement.ID)
fmt.Printf("Tx Hash: %s\n", settlement.TxHash)

// Retrieve Finality Certificate
certCtx, cancel := context.WithTimeout(ctx, 60*time.Second)
defer cancel()

cert, err := client.Deed.GetFinalityCertificate(certCtx, settlement.ID)
if err != nil {
    return fmt.Errorf("get certificate: %w", err)
}
fmt.Printf("Certificate: %s | Validators: %d\n",
    cert.CertificateHash, len(cert.Signatures))

Concurrent Usage

The Go client is safe for concurrent use across goroutines. Use errgroup for parallel requests:

package main

import (
    "context"
    "fmt"
    "sync"

    swss "github.com/swsschain/go-sdk"
    "golang.org/x/sync/errgroup"
)

func fetchMultipleBalances(client *swss.Client, addresses []string) (map[string]string, error) {
    ctx := context.Background()
    g, ctx := errgroup.WithContext(ctx)

    mu := sync.Mutex{}
    results := make(map[string]string, len(addresses))

    for _, addr := range addresses {
        addr := addr  // capture loop variable
        g.Go(func() error {
            balance, err := client.GetBalance(ctx, addr)
            if err != nil {
                return fmt.Errorf("balance for %s: %w", addr, err)
            }
            mu.Lock()
            results[addr] = swss.FormatSWSSCoin(balance)
            mu.Unlock()
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return nil, err
    }
    return results, nil
}

Error Types

import "github.com/swsschain/go-sdk/errors"

// Check specific error types
var rpcErr *errors.RPCError
var deedErr *errors.DeedError
var revertErr *errors.TransactionRevertedError

switch {
case errors.As(err, &revertErr):
    fmt.Printf("Reverted: %s (data: %s)\n", revertErr.Reason, revertErr.Data)
case errors.As(err, &deedErr):
    fmt.Printf("Deed error %d: %s\n", deedErr.Code, deedErr.Message)
case errors.As(err, &rpcErr):
    fmt.Printf("RPC error %d: %s\n", rpcErr.Code, rpcErr.Message)
default:
    return fmt.Errorf("unexpected error: %w", err)
}