Go SDK Reference

The Go SDK (github.com/ULedgerInc/golang-sdk) is the primary integration layer for ULedger. It handles wallet key management, transaction construction and signing, submission, polling, and end-to-end test harnesses.

---

Installation

go get github.com/ULedgerInc/golang-sdk

Or clone and build locally:

git clone https://github.com/ULedgerInc/golang-sdk
cd golang-sdk
go build ./...

---

Command-Line Tools

Wallet Management

cmd/generate_wallets

Generates new wallet keypairs from BIP39 entropy.

go run ./cmd/generate_wallets [flags]

Flags:
  --type    Key algorithm: secp256k1 | ed25519 | mldsa87 | bls12377 (required)
  --auth    Auth group preset: admin | wallet | readonly (optional)
  --count   Number of wallets to generate (default: 1)
  --out     Output directory for .ukey files (default: ./wallets)

Outputs .ukey files named <wallet-address>.ukey.

cmd/register_wallets

Submits TX_CREATE_WALLET transactions for all wallets in the wallets directory.

go run ./cmd/register_wallets [flags]

Flags:
  --config  Path to network config JSON (default: local-network.json)
  --dir     Wallet directory to register (default: ./wallets)

Reads wallet files, constructs TX_CREATE_WALLET payloads, signs with each wallet's private key, submits to the chain, and polls for confirmation.

cmd/alter_wallets

Submits ALTER_WALLET transactions from wallet configuration.

go run ./cmd/alter_wallets [flags]

Flags:
  --config  Path to alter config JSON

cmd/alter_entity

Submits ALTER_ENTITY transactions.

cmd/create_entities

Submits CREATE_ENTITY transactions from entity configuration.

---

End-to-End Test Harness

cmd/e2e_bootstrap: Step 1

Discovers chain configuration and provisions wallets for the E2E suite.

go run ./cmd/e2e_bootstrap [flags]

Flags:
  --config              Path to bootstrap config JSON
  --skip-council-wait   Skip waiting for council formation

What it does:

1. Connects to node endpoints and discovers chain ID and key type.
2. Generates and registers 7 role wallets + throughput signers.
3. Waits for council formation (unless skipped).
4. Emits a validated E2E config file + the exact cmd/e2e command to run next.

Run this once when setting up a new test cluster.

cmd/e2e: Step 2

Runs the full E2E test suite.

go run ./cmd/e2e [flags]

Flags:
  --config           Path to E2E config JSON (output from e2e_bootstrap)
  --only             Comma-separated list of domains to run (token,contract,walletops,data,council)
  --skip-throughput  Skip the throughput burst phase

Phases:

1. Preflight (cluster health check)
2. Domain suites run concurrently (token, contract, walletops, data, council)
3. Settle (wait for all transactions to commit)
4. Throughput burst
5. Settle again
6. Commit sweep
7. Cross-node consistency check (read from a different node than submission)

Exits 0 on all pass, 1 if any domain fails. Saves a timestamped JSON report to outputDir.

cmd/council: Single Domain

Runs only the council domain E2E suite.

go run ./cmd/council --config council-setup.json

cmd/identity: Identity Lifecycle

Runs the full identity lifecycle (DIDs, entities, recovery, credentials).

go run ./cmd/identity --config identities.json

Steps: DID creation, entity creation, child entity, metadata alter, recovery config, access list, ownership transfer, credential issuance, recovery execution.

---

Individual Domain Runners (Deprecated Manual Utilities)

These run single transactions without polling. Replaced by the domain runners in the E2E suite. Use for quick one-off testing only.

Command	Description
cmd/erc20	Single ERC-20 operation.
cmd/erc721	Single ERC-721 operation.
cmd/erc1155	Single ERC-1155 operation.
cmd/deploy_contracts	Deploy a contract without polling.
cmd/invoke_contract	Invoke a contract function without polling.
cmd/upgrade_rollback_contract	Upgrade or rollback a contract without polling.

---

Utilities

Command	Description
cmd/test_suite	Raw throughput burst for load testing pre-registered chains.
cmd/test_block	Submit a test block transaction.
cmd/test_results	Read and display a test report JSON file.
cmd/operator	Operator credential management.
cmd/transactions	Query and display transaction history.
cmd/generate_token	Generate a JWT token for API authentication.

---

Config Schema

Network Config (Base)

{
    "nodeEndpoints": ["http://localhost:8081", "..."],
    "keyType": "secp256k1",
    "blockchainId": "<hex-chain-id>",
    "verbose": false,
    "insecureSkipVerify": false
}

Field	Type	Default	Description
nodeEndpoints	array	required	HTTP URLs of validator nodes.
keyType	string	required	Chain key algorithm.
blockchainId	string	required	Target chain ID.
verbose	bool	false	Enable verbose SDK logging.
insecureSkipVerify	bool	false	Skip TLS verification (dev only).

E2E Config (Full)

{
    "nodeEndpoints": [...],
    "blockchainId": "...",
    "chainKeyType": "mldsa87",
    "passphrase": "",
    "outputDir": "./e2e_runs",
    "endpointStrategy": "roundrobin",
    "poll": {
        "intervalSeconds": 1,
        "timeoutSeconds": 80
    },
    "settle": {
        "intervals": 3,
        "intervalSeconds": 2
    },
    "throughput": {
        "count": 200,
        "intervalMs": 250,
        "concurrent": 100
    },
    "consistency": {
        "nodeIndex": 1
    },
    "domains": {
        "token": {
            "enabled": true,
            "wallets": {
                "owner": "./wallets/<hash>.ukey",
                "counterparty": "./wallets/<hash>.ukey",
                "spender": "./wallets/<hash>.ukey"
            }
        },
        "contract": {
            "enabled": true,
            "wallets": {
                "owner": "./wallets/<hash>.ukey",
                "other": "./wallets/<hash>.ukey"
            }
        },
        "walletops": {
            "enabled": true,
            "wallets": {
                "root": "./wallets/<hash>.ukey"
            }
        },
        "data": {
            "enabled": true,
            "wallets": {
                "sender": "./wallets/<hash>.ukey"
            }
        },
        "council": {
            "enabled": true,
            "sources": {
                "address": "<deployed-contract-address>"
            },
            "wallets": {
                "owner": "./wallets/<hash>.ukey",
                "member:alice": "./wallets/<hash>.ukey",
                "member:bob": "./wallets/<hash>.ukey",
                "agent:alice": "./wallets/<hash>.ukey",
                "agent:bob": "./wallets/<hash>.ukey"
            }
        }
    }
}

Endpoint Strategy

Value	Behavior
roundrobin	Distribute submissions across all endpoints in order.
random	Pick a random endpoint for each submission.
single	Use only the first endpoint.

Required Wallet Roles Per Domain

Domain	Required Roles
token	owner, counterparty, spender
contract	owner, other
walletops	root
data	sender
council	owner, member:* (N members), agent:* (N agents)

Wallet isolation: No wallet address may appear in more than one domain. The config validator enforces this.

---

Wallet File Format (.ukey)

The .ukey file contains the wallet's private key material, encoded for the key algorithm. Fields vary by algorithm.

{
    "address": "<wallet-address>",
    "keyType": "mldsa87",
    "publicKey": "<hex>",
    "privateKey": "<hex>",
    "mnemonic": "<BIP39 mnemonic phrase>",
    "passphrase": ""
}

Passphrase-protected wallets encrypt the private key bytes. An empty passphrase means unencrypted.

---

SDK Package Overview

Package	Purpose
pkg/wallet	Load wallet from .ukey file, derive address, sign.
pkg/transaction	Build and sign transaction payloads for all TX types.
pkg/txconfirm	Poll for transaction receipt with configurable timeout.
pkg/e2e	E2E pipeline engine: config loading, domain runners, reporting.
pkg/bootstrap	Wallet provisioning for E2E setup.
pkg/council	Council domain runner: member add, agent auth, proposal lifecycle.
pkg/identity	Identity lifecycle: DIDs, entities, recovery, credentials.
pkg/credential	VC issuance, JWT encoding, status list management.
pkg/token	Token domain runner: ERC-20/721/1155 operations.
pkg/contract	Contract domain runner: deploy, invoke, upgrade, rollback.
pkg/walletops	Wallet operations domain: tree creation, auth grant, cascade disable.
pkg/data	Data domain runner: byte-exact round-trip, large payload, dedup.
pkg/crypto	Key generation, signing, verification for all supported algorithms.
pkg/auth	Challenge-based authentication, JWT issuance.
pkg/operator	Operator credential management.
pkg/audit	Audit verification utilities.
pkg/utils	HTTP client, retry logic, JSON helpers.

---

Reading E2E Reports

Reports are saved as timestamped JSON files in outputDir:

e2e_runs/
  report_2026-10-16T14:23:45Z.json

Report structure:

{
    "timestamp": "2026-10-16T14:23:45Z",
    "passed": true,
    "domains": {
        "token": { "passed": true, "steps": [...] },
        "contract": { "passed": true, "steps": [...] },
        "walletops": { "passed": true, "steps": [...] },
        "data": { "passed": true, "steps": [...] },
        "council": { "passed": true, "steps": [...] }
    },
    "throughput": {
        "submitted": 200,
        "confirmed": 200,
        "durationMs": 4200,
        "tps": 47.6
    },
    "negativeTests": {
        "passed": true,
        "results": [...]
    }
}

Steps marked "denied": true in negative test results are reported as PASS; the expected behavior is rejection.

---

Dependencies

Dependency	Purpose
github.com/cloudflare/circl	Post-quantum crypto: ML-DSA-87, BLS12-377.
github.com/consensys/gnark-crypto	Elliptic curve operations: secp256k1, Ed25519.
github.com/tyler-smith/go-bip39	BIP39 mnemonic generation for wallet entropy.
github.com/google/uuid	UUID generation for request IDs.
golang.org/x/crypto	AES, SHA3, and other standard crypto.
github.com/urfave/cli/v3	CLI flag parsing for all command-line tools.