Go SDK (`github.com/rivellum/sdk/go`)

The official Go client library for the Rivellum network. Synchronous API backed by Go's net/http. Suitable for backend services, data pipelines, and CLI tooling.

Installation

go get github.com/rivellum/sdk/go

Quick Start

package main

import (
    "fmt"
    "time"
    "github.com/rivellum/sdk/go"
)

func main() {
    client := rivellum.NewClient(
        "https://rpc.rivellum.network",
        rivellum.WithTimeout(30*time.Second),
    )

    balance, err := client.GetBalance("a1b2c3...64hex")
    if err != nil {
        panic(err)
    }
    fmt.Printf("Balance: %s, Nonce: %d\n", balance.Balance, balance.Nonce)
}

Constructor

func NewClient(nodeURL string, opts ...ClientOption) *Client

Parameter	Type	Description
`nodeURL`	`string`	Node RPC base URL.
`opts`	`...ClientOption`	Optional configuration functions.

Options

func WithTimeout(d time.Duration) ClientOption
func WithHTTPClient(h *http.Client) ClientOption

// Custom timeout
client := rivellum.NewClient("https://rpc.rivellum.network", rivellum.WithTimeout(60*time.Second))

// Custom HTTP client (e.g., with proxy)
httpClient := &http.Client{Transport: myTransport}
client := rivellum.NewClient("https://rpc.rivellum.network", rivellum.WithHTTPClient(httpClient))

Error Types

type NodeError struct {
    StatusCode int
    Body       string
}

func (e *NodeError) Error() string // "rivellum: node returned 404: ..."

HTTP errors from the node are returned as *NodeError. Check StatusCode for 404, 501, etc. Network errors return standard Go errors.

Health & Info

`Health()`

func (c *Client) Health() (*HealthResponse, error)

type HealthResponse struct {
    Status  string `json:"status"`
    Service string `json:"service"`
}

`IsHealthy()`

func (c *Client) IsHealthy() bool

Returns true if Health().Status == "ok".

`GetChainInfo()`

func (c *Client) GetChainInfo() (*ChainInfo, error)

type ChainInfo struct {
    Version  string       `json:"version"`
    Height   uint64       `json:"height"`
    Features FeatureFlags `json:"features"`
}

type FeatureFlags struct {
    BatchingEnabled          bool `json:"batching_enabled"`
    MoveVMEnabled            bool `json:"move_vm_enabled"`
    GovernanceEnabled        bool `json:"governance_enabled"`
    CommitteeRotationEnabled bool `json:"committee_rotation_enabled"`
    SlashingEnabled          bool `json:"slashing_enabled"`
    LightClientEnabled       bool `json:"light_client_enabled"`
    BridgeEnabled            bool `json:"bridge_enabled"`
    PrivateIntentsEnabled    bool `json:"private_intents_enabled"`
    ZkProofsEnabled          bool `json:"zk_proofs_enabled"`
}

Account Methods

`GetBalance(address)`

func (c *Client) GetBalance(address string) (*Balance, error)

type Balance struct {
    Address  string            `json:"address"`
    Balance  string            `json:"balance"`
    Nonce    uint64            `json:"nonce"`
    Balances map[string]string `json:"balances,omitempty"` // Asset sub-balances
}

`GetLedgerTip()`

func (c *Client) GetLedgerTip() (*LedgerTip, error)

type LedgerTip struct {
    Height      uint64 `json:"height"`
    Root        string `json:"root"`
    TimestampMs uint64 `json:"timestamp_ms"`
    IntentCount uint64 `json:"intent_count"`
}

Contract (Mist) Methods

`Contract(contractID)`

func (c *Client) Contract(contractID string) *ContractHandle

Returns a ContractHandle bound to a deployed contract.

`ContractHandle.Call(function, args)`

func (h *ContractHandle) Call(function string, args map[string]interface{}) (*CallResult, error)

type CallResult struct {
    ReceiptID  string `json:"receipt_id"`
    ContractID string `json:"contract_id"`
    Function   string `json:"function"`
    Status     string `json:"status"`
    IntentID   string `json:"intent_id,omitempty"`
}

`ContractHandle.GetInfo()`

func (h *ContractHandle) GetInfo() (*ContractInfo, error)

type ContractInfo struct {
    ContractID      string `json:"contract_id"`
    CodeHash        string `json:"code_hash"`
    DeployedAt      uint64 `json:"deployed_at"`
    Deployer        string `json:"deployer,omitempty"`
    BundleSizeBytes uint64 `json:"bundle_size_bytes"`
    PviSpecVersion  uint32 `json:"pvi_spec_version"`
}

`DeployContract(req)`

func (c *Client) DeployContract(req *DeployRequest) (*DeployResult, error)

type DeployRequest struct {
    Bytecode string      `json:"bytecode"`
    Args     interface{} `json:"args,omitempty"`
}

type DeployResult struct {
    ContractID string `json:"contract_id"`
    ReceiptID  string `json:"receipt_id"`
    Status     string `json:"status"`
}

`GetReceipt(receiptID)` / `GetReceipts()`

func (c *Client) GetReceipt(receiptID string) (*Receipt, error)
func (c *Client) GetReceipts() ([]Receipt, error)

type Receipt struct {
    ReceiptID    string                 `json:"receipt_id"`
    ContractID   string                 `json:"contract_id"`
    Function     string                 `json:"function"`
    Status       string                 `json:"status"`
    FailureCode  string                 `json:"failure_code,omitempty"`
    Slot         uint64                 `json:"slot"`
    FeeCharged   uint64                 `json:"fee_charged"`
    IntentID     string                 `json:"intent_id,omitempty"`
    Effects      map[string]interface{} `json:"effects,omitempty"`
}

Envelope Submission

`SubmitEnvelope(envelope)`

func (c *Client) SubmitEnvelope(envelope *EncryptedEnvelope) (*EnvelopeSubmitResult, error)

type EncryptedEnvelope struct {
    Sender           string `json:"sender"`
    Nonce            uint64 `json:"nonce"`
    LaneHint         uint8  `json:"lane_hint"`
    EpochID          uint64 `json:"epoch_id"`
    MaxFee           string `json:"max_fee"`
    EncryptedPayload string `json:"encrypted_payload"`
    Signature        string `json:"signature"`
}

type EnvelopeSubmitResult struct {
    Status          string `json:"status"`           // "accepted" | "rejected"
    EnvelopeID      string `json:"envelope_id"`
    BatchWindowID   string `json:"batch_window_id,omitempty"`
    RejectionReason string `json:"rejection_reason,omitempty"`
}

`SubmitEnvelopeBatch(envelopes)`

func (c *Client) SubmitEnvelopeBatch(envelopes []*EncryptedEnvelope) (*EnvelopeBatchSubmitResult, error)

type EnvelopeBatchSubmitResult struct {
    Accepted int `json:"accepted"`
    Rejected int `json:"rejected"`
}

`GetEnvelopeStatus(envelopeID)`

func (c *Client) GetEnvelopeStatus(envelopeID string) (*EnvelopeStatus, error)

type EnvelopeStatus struct {
    EnvelopeID      string `json:"envelope_id"`
    Status          string `json:"status"`    // received→admitted→batched→sealed→decrypted→ordered→executed→finalized
    Sender          string `json:"sender"`
    Nonce           uint64 `json:"nonce"`
    LaneID          string `json:"lane_id"`
    EpochID         uint64 `json:"epoch_id"`
    MaxFee          string `json:"max_fee"`
    BatchID         string `json:"batch_id,omitempty"`
    RejectionReason string `json:"rejection_reason,omitempty"`
    AdmittedAtMs    uint64 `json:"admitted_at_ms,omitempty"`
    SealedAtMs      uint64 `json:"sealed_at_ms,omitempty"`
    IntentID        string `json:"intent_id,omitempty"`
}

`GetBatchInfo(batchID)`

func (c *Client) GetBatchInfo(batchID string) (*BatchInfo, error)

type BatchInfo struct {
    BatchID       string   `json:"batch_id"`
    LaneID        string   `json:"lane_id"`
    EpochID       uint64   `json:"epoch_id"`
    State         string   `json:"state"`   // filling|sealed|decrypted|ordered|dispatched
    EnvelopeCount int      `json:"envelope_count"`
    TotalBytes    int      `json:"total_bytes"`
    SealHash      string   `json:"seal_hash,omitempty"`
    EnvelopeIDs   []string `json:"envelope_ids"`
    SealedAtMs    uint64   `json:"sealed_at_ms,omitempty"`
}

`GetAdmissionTicket(intentID)`

func (c *Client) GetAdmissionTicket(intentID string) (*AdmissionTicket, error)

type AdmissionTicket struct {
    AdmissionID    string `json:"admission_id"`
    Sender         string `json:"sender"`
    ValidatedNonce uint64 `json:"validated_nonce"`
    IntentID       string `json:"intent_id"`
    IdempotencyKey string `json:"idempotency_key,omitempty"`
    AcceptedAtMs   uint64 `json:"accepted_at_ms"`
    Status         string `json:"status"`   // admitted|dispatched|committed|finalized
}

Simulation

`SimulateIntent(req)`

func (c *Client) SimulateIntent(req *SimulationRequest) (*SimulationResult, error)

type SimulationRequest struct {
    Intent          map[string]interface{} `json:"intent"`
    AtHeight        *uint64                `json:"at_height,omitempty"`
    MaxGasOverride  *uint64                `json:"max_gas_override,omitempty"`
    ValidateSignature bool                 `json:"validate_signature,omitempty"`
}

type SimulationResult struct {
    Status        string      `json:"status"`
    GasUsed       uint64      `json:"gas_used"`
    FeeEstimate   string      `json:"fee_estimate"`
    StateDiff     *StateDiff  `json:"state_diff,omitempty"`
    FailureReason string      `json:"failure_reason,omitempty"`
}

Events & Ledger

`GetRecentEvents()`

func (c *Client) GetRecentEvents() (*EventsResponse, error)

type EventsResponse struct {
    Events     []ChainEvent `json:"events"`
    Total      int          `json:"total"`
    NextCursor string       `json:"next_cursor,omitempty"`
}

type ChainEvent struct {
    EventID    string      `json:"event_id"`
    IntentID   string      `json:"intent_id,omitempty"`
    Topic      string      `json:"topic"`
    Contract   string      `json:"contract,omitempty"`
    BatchHeight uint64     `json:"batch_height"`
    TimestampMs uint64     `json:"timestamp_ms"`
    Data       interface{} `json:"data"`
}

`QueryEvents(q)`

func (c *Client) QueryEvents(q *EventsQuery) (*EventsResponse, error)

type EventsQuery struct {
    Topic       string `json:"topic,omitempty"`
    Contract    string `json:"contract,omitempty"`
    Address     string `json:"address,omitempty"`
    IntentID    string `json:"intent_id,omitempty"`
    MinHeight   uint64 `json:"min_height,omitempty"`
    MaxHeight   uint64 `json:"max_height,omitempty"`
    Limit       int    `json:"limit,omitempty"`
    FromCursor  string `json:"from_cursor,omitempty"`
}

PoUW

`GetProvers()`

func (c *Client) GetProvers() ([]ProverStats, error)

type ProverStats struct {
    ProverID             string  `json:"prover_id"`
    JobsCompleted        uint64  `json:"jobs_completed"`
    JobsFailed           uint64  `json:"jobs_failed"`
    TotalFeeEarned       string  `json:"total_fee_earned"`
    AvgCompletionTimeMs  float64 `json:"avg_completion_time_ms"`
    LastSeenMs           uint64  `json:"last_seen_ms"`
}

`GetPendingJobs()`

func (c *Client) GetPendingJobs() ([]JobSummary, error)

type JobSummary struct {
    JobID       string  `json:"job_id"`
    Tier        string  `json:"tier"`      // Low|Medium|High
    TraceHash   []byte  `json:"trace_hash"`
    FeeBudget   string  `json:"fee_budget"`
    CreatedAtMs uint64  `json:"created_at_ms"`
    DeadlineMs  uint64  `json:"deadline_ms"`
}

Faucet (Testnet)

`FaucetMint(address, amount)`

func (c *Client) FaucetMint(address string, amount string) (*FaucetMintResult, error)

type FaucetMintResult struct {
    Success  bool   `json:"success"`
    TxHash   string `json:"tx_hash"`
    Minted   string `json:"minted"`
    Address  string `json:"address"`
    Message  string `json:"message"`
}

Governance

`GetGovernanceParams()`

func (c *Client) GetGovernanceParams() (*GovernanceParams, error)

type GovernanceParams struct {
    EpochLengthSlots     uint64 `json:"epoch_length_slots"`
    SlotDurationMs       uint64 `json:"slot_duration_ms"`
    MaxCommitteeSize     uint64 `json:"max_committee_size"`
    MinStakeToPropose    string `json:"min_stake_to_propose"`
    VotingPeriodSlots    uint64 `json:"voting_period_slots"`
    ExecutionDelaySlots  uint64 `json:"execution_delay_slots"`
}

`GetGovernanceHistory()`

func (c *Client) GetGovernanceHistory() ([]Proposal, error)

type Proposal struct {
    ID               uint64 `json:"id"`
    Key              string `json:"key"`
    OldValue         string `json:"old_value"`
    NewValue         string `json:"new_value"`
    ProposedAtSlot   uint64 `json:"proposed_at_slot"`
    ActivationSlot   uint64 `json:"activation_slot"`
    ProposedBy       string `json:"proposed_by"`
    Status           string `json:"status"`
}

NFTs

`GetNft(nftID)` / `GetNftsOwnedBy(address)` / `GetNftTransferHistory(nftID)`

func (c *Client) GetNft(nftID string) (*NftMetadata, error)
func (c *Client) GetNftsOwnedBy(address string) (*NftListResponse, error)
func (c *Client) GetNftTransferHistory(nftID string) ([]map[string]interface{}, error)

type NftMetadata struct {
    NftID       string                 `json:"nft_id"`
    CollectionID string                `json:"collection_id"`
    Owner       string                 `json:"owner"`
    Creator     string                 `json:"creator"`
    TokenID     string                 `json:"token_id"`
    Metadata    map[string]interface{} `json:"metadata"`
    MintedAt    uint64                 `json:"minted_at"`
}

type NftListResponse struct {
    Items []NftMetadata `json:"items"`
    Total int           `json:"total"`
    Page  int           `json:"page"`
    Limit int           `json:"limit"`
}

`ListCollections()` / `GetCollection(id)` / `GetCollectionNfts(id)`

func (c *Client) ListCollections() (*CollectionListResponse, error)
func (c *Client) GetCollection(collectionID string) (*NftCollection, error)
func (c *Client) GetCollectionNfts(collectionID string) (*NftListResponse, error)

type NftCollection struct {
    CollectionID string `json:"collection_id"`
    Name         string `json:"name"`
    Creator      string `json:"creator"`
    TotalSupply  uint64 `json:"total_supply"`
    CreatedAt    uint64 `json:"created_at"`
}

Prefabs

`ListPrefabs()` / `GetPrefab(prefabID)`

func (c *Client) ListPrefabs() ([]PrefabDefinition, error)
func (c *Client) GetPrefab(prefabID string) (*PrefabDefinition, error)

type PrefabDefinition struct {
    PrefabID     string   `json:"prefab_id"`
    Name         string   `json:"name"`
    Description  string   `json:"description"`
    Category     string   `json:"category"`
    Tags         []string `json:"tags"`
    Version      string   `json:"version"`
    CodeHash     string   `json:"code_hash"`
    Parameters   []PrefabParameter `json:"parameters"`
}

Bridge & XCM

func (c *Client) GetBridgeStatus() (*BridgeStatus, error)
func (c *Client) GetBridgeChains() ([]map[string]interface{}, error)
func (c *Client) GetBridgeMessages() ([]map[string]interface{}, error)
func (c *Client) GetProtocolUpgrades() ([]map[string]interface{}, error)

Randomness

`GetRandomnessBeacon()`

func (c *Client) GetRandomnessBeacon() (*RandomnessBeacon, error)

type RandomnessBeacon struct {
    Height      uint64 `json:"height"`
    Output      string `json:"output"`
    Proof       string `json:"proof"`
    Producer    string `json:"producer"`
    TimestampMs uint64 `json:"timestamp_ms"`
    Verified    bool   `json:"verified"`
}

Constraint Engine

`GetAssetConstraints(assetID)`

func (c *Client) GetAssetConstraints(assetID string) (*AssetConstraints, error)

type AssetConstraints struct {
    AssetID      string   `json:"asset_id"`
    Constrained  bool     `json:"constrained"`
    PolicyID     string   `json:"policy_id,omitempty"`
    Paused       bool     `json:"paused,omitempty"`
    Capabilities []string `json:"capabilities,omitempty"`
}

`GetFreezeStatus(assetID, account)`

func (c *Client) GetFreezeStatus(assetID, account string) (*FreezeStatus, error)

type FreezeStatus struct {
    Frozen      bool   `json:"frozen"`
    Reason      string `json:"reason,omitempty"`
    FrozenAtMs  uint64 `json:"frozen_at_ms,omitempty"`
}

Move VM Endpoint Status

Public production APIs do not expose /move/* routes.

The Go SDK keeps the following methods for compatibility, but they return explicit errors on production networks:

func (c *Client) CallMoveView(req *MoveViewRequest) (map[string]interface{}, error)
func (c *Client) GetMoveModule(moduleID string) (map[string]interface{}, error)
func (c *Client) GetMoveModuleABI(moduleID string) (map[string]interface{}, error)
func (c *Client) GetAccountResources(address string) ([]map[string]interface{}, error)
func (c *Client) GetAccountModules(address string) ([]map[string]interface{}, error)

Use Mist and /v1/* RPC capabilities for public production workflows.

Full Example

package main

import (
    "fmt"
    "log"
    "time"
    rivellum "github.com/rivellum/sdk/go"
)

func main() {
    client := rivellum.NewClient(
        "https://rpc.rivellum.network",
        rivellum.WithTimeout(30*time.Second),
    )

    // Health check
    if !client.IsHealthy() {
        log.Fatal("node is not healthy")
    }

    // Get chain info
    chain, err := client.GetChainInfo()
    if err != nil { log.Fatal(err) }
    fmt.Printf("Chain version: %s, height: %d\n", chain.Version, chain.Height)
    fmt.Printf("Features: batching=%v, moveVM=%v\n",
        chain.Features.BatchingEnabled, chain.Features.MoveVMEnabled)

    // Get balance
    bal, err := client.GetBalance("a1b2c3...64hex")
    if err != nil { log.Fatal(err) }
    fmt.Printf("Balance: %s (nonce %d)\n", bal.Balance, bal.Nonce)

    // Submit an envelope
    result, err := client.SubmitEnvelope(&rivellum.EncryptedEnvelope{
        Sender:           "a1b2...64hex",
        Nonce:            bal.Nonce,
        LaneHint:         3,
        EpochID:          100,
        MaxFee:           "5000",
        EncryptedPayload: "deadbeef...",
        Signature:        "sig...",
    })
    if err != nil { log.Fatal(err) }
    if result.Status == "accepted" {
        fmt.Printf("Envelope %s accepted\n", result.EnvelopeID)

        // Poll until finalized
        for {
            status, _ := client.GetEnvelopeStatus(result.EnvelopeID)
            if status == nil { break }
            fmt.Printf("Status: %s\n", status.Status)
            if status.Status == "finalized" || status.Status == "rejected" { break }
            time.Sleep(2 * time.Second)
        }
    }

    // Query recent events
    events, err := client.QueryEvents(&rivellum.EventsQuery{
        Topic: "native.transfer",
        Limit: 20,
    })
    if err != nil { log.Fatal(err) }
    for _, e := range events.Events {
        fmt.Printf("Event %s: %s at height %d\n", e.EventID, e.Topic, e.BatchHeight)
    }

    // Get provers
    provers, _ := client.GetProvers()
    for _, p := range provers {
        fmt.Printf("Prover %s: %d jobs completed\n", p.ProverID, p.JobsCompleted)
    }
}

Go SDK (`github.com/rivellum/sdk/go`)

Installation

Quick Start

Constructor

Options

Error Types

Health & Info

Health()

IsHealthy()

GetChainInfo()

Account Methods

GetBalance(address)

GetLedgerTip()

Contract (Mist) Methods

Contract(contractID)

ContractHandle.Call(function, args)

ContractHandle.GetInfo()

DeployContract(req)

GetReceipt(receiptID) / GetReceipts()

Envelope Submission

SubmitEnvelope(envelope)

SubmitEnvelopeBatch(envelopes)

GetEnvelopeStatus(envelopeID)

GetBatchInfo(batchID)

GetAdmissionTicket(intentID)