GitHub - arkade-os/go-sdk: The Arkade SDK is a Go package for building Bitcoin wallets with support for both on-chain and off-chain transactions via the Ark protocol.

Arkade Go SDK

The complete API documentation for the Go SDK is automatically generated and published on pkg.go.dev with each GitHub release. To view the documentation, visit: https://pkg.go.dev/github.com/arkade-os/go-sdk

Installation

To install the Arkade Go SDK, use the following command:

go get github.com/arkade-os/go-sdk

Usage

Here's a comprehensive guide on how to use the Arkade Go SDK:

1. Setting up the Ark Client

NewArkClient(datadir string, opts ...ClientOption) creates a brand new client and can't be used to load an existing one.
LoadArkClient(datadir string, opts ...ClientOption) loads an existing client and can't be used to create a new one.
Both accept one required parameter plus optional client options:

datadir — path to the directory where wallet and transaction data are persisted. Pass "" to use in-memory storage (useful for testing, loading an existing client won't work for obvious reasons).
opts — optional ClientOption values:
- WithRefreshDbInterval(d time.Duration) — enable periodic background refresh of the local database from the server. Must be at least 30s. Disabled by default (zero value).
- WithVerbose() — enables verbose logging.

import arksdk (
    "errors"
    "log"

    "github.com/arkade-os/go-sdk"
)

// In-memory storage
client, err := arksdk.NewArkClient("")

// Persistent storage
var client arksdk.ArkClient
var err error
// Try to load the client (with default options).
client, err = arksdk.LoadArkClient("/path/to/data/dir")
if err != nil {
    if !errors.Is(err, arksdk.ErrNotInitialized) {
        return err
    }
    // If not initialized, create a new one (with default options).
    client, err = arksdk.NewArkClient("/path/to/data/dir")
    if err != nil {
        log.Fatal(err)
    }
}

// Client with periodic DB refresh every 5 minutes and verbose logs
client, err := arksdk.NewArkClient(
    "/path/to/data/dir", arksdk.WithRefreshDbInterval(5 * time.Minute), arksdk.WithVerbose(),
)

Once you have a client, call Init to connect it to an Arkade server and set up the wallet:

// Minimal — single-key wallet, default explorer URL for the network.
if err := client.Init(ctx, "localhost:7070", "your_seed", "your_password"); err != nil {
    return fmt.Errorf("failed to initialize wallet: %s", err)
}

// Restore an existing wallet from seed.
if err := client.Init(ctx, "localhost:7070", "your_seed", "your_password"); err != nil {
    return fmt.Errorf("failed to restore wallet: %s", err)
}

// Custom explorer URL.
if err := client.Init(
    ctx, "localhost:7070", "your_seed", "your_password",
    arksdk.WithExplorerURL("https://example.com"),
); err != nil {
    return fmt.Errorf("failed to initialize wallet: %s", err)
}

// Bring your own wallet implementation.
if err := client.Init(
    ctx, "localhost:7070", "your_seed", "your_password",
    arksdk.WithWallet(myWalletService),
); err != nil {
    return fmt.Errorf("failed to initialize wallet: %s", err)
}

2. Client Configuration Options

Init has the following signature:

Init(ctx context.Context, serverUrl, seed, password string, opts ...InitOption) error

serverUrl — address of the Arkade server (e.g. "localhost:7070").
seed — hex-encoded private key for wallet initialization or restoration.
password — password used to encrypt and protect the wallet.
opts — optional functional options:
- WithExplorerURL(url string) — override the default mempool explorer URL for the network.
- WithWallet(wallet wallet.WalletService) — supply a custom wallet implementation instead of the built-in single-key wallet.

Note: Always keep your seed and password secure. Never share them or store them in plaintext.

3. Wallet Operations

Unlock and Lock the Wallet

if err := arkClient.Unlock(ctx, password); err != nil {
    log.Fatal(err)
}
defer arkClient.Lock(ctx)

Receive Funds

The old Receive API has been split into three dedicated methods:

onchainAddr, err := arkClient.NewOnchainAddress(ctx)
if err != nil {
    log.Fatal(err)
}
log.Infof("Onchain address: %s", onchainAddr)

boardingAddr, err := arkClient.NewBoardingAddress(ctx)
if err != nil {
    log.Fatal(err)
}
log.Infof("Boarding address: %s", boardingAddr)

offchainAddr, err := arkClient.NewOffchainAddress(ctx)
if err != nil {
    log.Fatal(err)
}
log.Infof("Offchain address: %s", offchainAddr)

Check Balance

balance, err := arkClient.Balance(ctx)
if err != nil {
    log.Fatal(err)
}
log.Infof("Onchain balance: %d", balance.OnchainBalance.SpendableAmount)
log.Infof("Offchain balance: %d", balance.OffchainBalance.Total)

// Asset balances are keyed by asset ID (string).
for assetID, amount := range balance.AssetBalances {
    log.Infof("Asset %s balance: %d", assetID, amount)
}

Send Offchain

import clientTypes "github.com/arkade-os/arkd/pkg/client-lib/types"

// Send sats offchain.
receivers := []clientTypes.Receiver{
    {To: recipientOffchainAddr, Amount: 1000},
}
txid, err := arkClient.SendOffChain(ctx, receivers)
if err != nil {
    log.Fatal(err)
}
log.Infof("Transaction completed: %s", txid)

// Send assets offchain. If not specified, like in this example, the real recipient's amount defaults to 330 sats (dust).
assetReceivers := []clientTypes.Receiver{
    {
        To: recipientOffchainAddr,
        Assets: []clientTypes.Asset{
            {AssetId: assetID, Amount: 1200},
        },
    },
}
txid, err = arkClient.SendOffChain(ctx, assetReceivers)
if err != nil {
    log.Fatal(err)
}
log.Infof("Asset transfer completed: %s", txid)

Submit Transaction

SendOffChain is useful for simple send operations. But complex contract or collaborative transactions require more flexibility. In this case, you can use the TransportClient.SubmitTx and TransportClient.FinalizeTx APIs.

// Create a new transport client
transportClient, err := grpcclient.NewClient("localhost:7070")
require.NoError(t, err)

// Use ark-lib/tree util function to build ark and checkpoint transactions.
arkTx, checkpointTxs, err := offchain.BuildTxs(
	[]offchain.VtxoInput{
		// ... your inputs here
	},
	[]*wire.TxOut{
		// ... your outputs here
	},
	batchOutputSweepClosure,
)

signedArkTx, err := arkClient.SignTransaction(ctx, arkTx)
if err != nil {
	return "", err
}

arkTxid, _, signedCheckpointTxs, err := grpcclient.SubmitTx(ctx, signedArkTx, checkpointTxs)
if err != nil {
	return "", err
}

// Counter-sign and checkpoint txs and send them back to the server to complete the process.
finalCheckpointTxs := make([]string, 0, len(signedCheckpointTxs))
for _, checkpointTx := range signedCheckpointTxs {
	finalCheckpointTx, err := a.SignTransaction(ctx, checkpointTx)
	if err != nil {
		return "", nil
	}
	finalCheckpointTxs = append(finalCheckpointTxs, finalCheckpointTx)
}

if err = a.client.FinalizeTx(ctx, arkTxid, finalCheckpointTxs); err != nil {
	return "", err
}

Asset Operations

Arkade supports issuing, transferring, reissuing, and burning custom assets offchain.

Concepts:

An asset is identified by a string asset ID derived from the genesis transaction ID and group index.
A control asset is a special asset that grants authority to reissue a given asset. Holding the control asset vtxo in your wallet is required to call ReissueAsset.
Without a control asset, an issued asset has a fixed, immutable supply.

Issue Asset

import (
    "github.com/arkade-os/arkd/pkg/ark-lib/asset"
    clientTypes "github.com/arkade-os/arkd/pkg/client-lib/types"
)

// 1. Fixed supply — no control asset. Returns one asset ID.
txid, assetIds, err := arkClient.IssueAsset(ctx, 5000, nil, nil)
if err != nil {
    log.Fatal(err)
}
assetID := assetIds[0].String()
log.Infof("Issued asset %s in tx %s", assetID, txid)

// 2. With a new control asset issued together with the controlled one.
//    Returns two asset IDs: [controlAssetId, issuedAssetId].
txid, assetIds, err = arkClient.IssueAsset(ctx, 5000, clientTypes.NewControlAsset{Amount: 1}, nil)
if err != nil {
    log.Fatal(err)
}
controlAssetID := assetIds[0].String()
assetID = assetIds[1].String()
log.Infof("Control asset: %s, issued asset: %s", controlAssetID, assetID)

// 3. With an existing control asset.
//    Returns one asset ID for the newly issued asset.
txid, assetIds, err = arkClient.IssueAsset(
    ctx, 5000, clientTypes.ExistingControlAsset{ID: controlAssetID}, nil,
)
if err != nil {
    log.Fatal(err)
}
log.Infof("Issued asset %s under existing control asset", assetIds[0].String())

// Optional: attach metadata to the asset.
meta := []asset.Metadata{
    {Key: "name", Value: "My Token"},
    {Key: "ticker", Value: "MTK"},
}
txid, assetIds, err = arkClient.IssueAsset(ctx, 5000, clientTypes.NewControlAsset{Amount: 1}, meta)

Reissue Asset

The caller must hold the control asset vtxo in their wallet.

txid, err := arkClient.ReissueAsset(ctx, assetID, 1000)
if err != nil {
    log.Fatal(err)
}
log.Infof("Reissued 1000 units of %s in tx %s", assetID, txid)

Burn Asset

Destroys the specified amount. Any remaining balance is returned to the caller's address as change.

txid, err := arkClient.BurnAsset(ctx, assetID, 500)
if err != nil {
    log.Fatal(err)
}
log.Infof("Burned 500 units of %s in tx %s", assetID, txid)

4. Advanced Usage

Multiple Recipients

You can send to multiple recipients in a single transaction:

receivers := []clientTypes.Receiver{
    {To: recipient1OffchainAddr, Amount: amount1},
    {To: recipient2OffchainAddr, Amount: amount2},
}
txid, err = arkClient.SendOffChain(ctx, receivers)

Settle

Finalize pending boarding or preconfirmed funds into a commitment transaction:

// Basic settle
txid, err := arkClient.Settle(ctx)
if err != nil {
    log.Fatal(err)
}
log.Infof("commitment tx: %s", txid)

// Settle with automatic retries on failure (max 5)
txid, err = arkClient.Settle(ctx, arksdk.WithRetries(3))
if err != nil {
    log.Fatal(err)
}
log.Infof("commitment tx: %s", txid)

Cooperative Exit

To redeem offchain funds to onchain:

// Basic collaborative exit
txid, err := arkClient.CollaborativeExit(ctx, onchainAddress, redeemAmount)
if err != nil {
    log.Fatal(err)
}
log.Infof("commitment tx: %s", txid)

// Collaborative exit with automatic retries on failure (max 5)
txid, err = arkClient.CollaborativeExit(ctx, onchainAddress, redeemAmount, arksdk.WithRetries(3))
if err != nil {
    log.Fatal(err)
}
log.Infof("Redeemed with tx: %s", txid)

5. Additional Client Functions

The ArkClient interface exposes a number of utility methods beyond the basic workflow shown above. Here is a quick overview:

GetVersion() - return the SDK version.
GetConfigData(ctx) - retrieve Arkade server configuration details.
Init(ctx, serverUrl, seed, password, opts...) - create or restore a wallet and connect to the server. See §2 for available options.
IsLocked(ctx) - check if the wallet is currently locked.
Unlock(ctx, password) / Lock(ctx) - unlock or lock the wallet.
IsSynced(ctx) <-chan types.SyncEvent - returns a channel that emits once the local database has finished syncing after unlock.
Balance(ctx) - query onchain and offchain balances. The returned struct includes AssetBalances map[string]uint64 keyed by asset ID.
IssueAsset(ctx, amount, controlAsset, metadata) — mint a new offchain asset. Pass nil for a fixed-supply asset, types.NewControlAsset{Amount} to create a reissuable asset with a new control asset, or types.ExistingControlAsset{ID} to issue under an existing control asset. Returns the ark txid and the resulting asset IDs.
ReissueAsset(ctx, assetId, amount) — mint additional supply of an existing controllable asset. Requires the caller to hold the corresponding control asset vtxo.
BurnAsset(ctx, assetID, amount) — permanently destroy a quantity of an asset. Remaining balance is returned as change to the caller's address.
GetAddresses(ctx) - return all known onchain, offchain, boarding and redemption addresses.
NewOnchainAddress(ctx) / NewBoardingAddress(ctx) / NewOffchainAddress(ctx) - derive a fresh address of the respective type.
SendOffChain(ctx, receivers) - send funds offchain. Each clientTypes.Receiver can carry an Assets []clientTypes.Asset slice to transfer assets alongside sats.
Settle(ctx, opts ...BatchSessionOption) (string, error) - finalize pending or preconfirmed funds into a commitment transaction. Accepts WithRetries(n) to retry on failure (max 5 retries).
RegisterIntent(...) / DeleteIntent(...) - manage spend intents for collaborative transactions.
CollaborativeExit(ctx, addr, amount, opts ...BatchSessionOption) (string, error) - redeem offchain funds onchain. Accepts WithRetries(n) to retry on failure (max 5 retries).
Unroll(ctx) error - broadcast unroll transactions when ready.
CompleteUnroll(ctx, to string) (string, error) - finalize an unroll and sweep to an onchain address.
OnboardAgainAllExpiredBoardings(ctx) (string, error) - onboard again using expired boarding UTXOs.
WithdrawFromAllExpiredBoardings(ctx, to string) (string, error) - withdraw expired boarding amounts onchain.
ListVtxos(ctx) (spendable, spent []clientTypes.Vtxo, err error) - list virtual UTXOs. Each Vtxo includes an Assets []types.Asset field listing any assets it carries.
ListSpendableVtxos(ctx) - list only spendable virtual UTXOs.
Dump(ctx) (seed string, error) - export the wallet seed.
GetTransactionHistory(ctx) - fetch past transactions.
GetTransactionEventChannel(ctx), GetVtxoEventChannel(ctx) and GetUtxoEventChannel(ctx) - subscribe to wallet events.
FinalizePendingTxs(ctx, createdAfter *time.Time) ([]string, error) - finalize any pending transactions, optionally filtered by creation time.
RedeemNotes(ctx, notes) - redeem Arkade notes back to your wallet.
SignTransaction(ctx, tx) - sign an arbitrary transaction.
NotifyIncomingFunds(ctx, address) - wait until a specific offchain address receives funds.
Stop() - stop any running listeners.

6. Transport Client

For lower-level control over transaction batching you can use the TransportClient interface directly:

GetInfo(ctx) - return server configuration and network data.
RegisterIntent(ctx, signature, message) and DeleteIntent(ctx, signature, message) - manage collaborative intents.
ConfirmRegistration(ctx, intentID) - confirm intent registration on chain.
SubmitTreeNonces(ctx, batchId, cosignerPubkey, nonces) and SubmitTreeSignatures(ctx, batchId, cosignerPubkey, sigs) - coordinate cosigner trees.
SubmitSignedForfeitTxs(ctx, signedForfeitTxs, signedCommitmentTx) - provide fully signed forfeit and commitment transactions.
GetEventStream(ctx, topics) - subscribe to batch events from the server.
SubmitTx(ctx, signedArkTx, checkpointTxs) and FinalizeTx(ctx, arkTxid, finalCheckpointTxs) - submit collaborative transactions.
GetTransactionsStream(ctx) - stream transaction notifications.
Close() - close the transport connection.

See the pkg.go.dev documentation for detailed API information.

Testing

Run integration tests (start nigiri if needed first):

make regtest
make integrationtest
make regtestdown

Full Example

The snippet below shows the complete flow from client creation to an offchain send:

package main

import (
    "context"
    "fmt"
    "log"

    arksdk "github.com/arkade-os/go-sdk"
    clientTypes "github.com/arkade-os/arkd/pkg/client-lib/types"
)

func main() {
    ctx := context.Background()
	prvkey := "ff694aab53abf53843f5cd1ffd8d488d743b08b35f48598bdcbab3f71d430e01"
	password := "secret"
	serverUrl := "localhost:7070"

    // Create a persistent client with debug logs enabled.
    client, err := arksdk.NewArkClient("/path/to/data/dir")
    if err != nil {
        log.Fatal(err)
    }
    defer client.Stop()

    // Connect to the server and set up the wallet.
    if err := client.Init(ctx, serverUrl, prvkey, password); err != nil {
        log.Fatal(err)
    }

    // Unlock the wallet to start syncing.
    if err := client.Unlock(ctx, password); err != nil {
        log.Fatal(err)
    }
    defer client.Lock(ctx)

    // Wait for the local database to finish syncing.
    syncCh := client.IsSynced(ctx)
    if event := <-syncCh; event.Err != nil {
        log.Fatal(event.Err)
    }

    // Generate a fresh offchain address to receive funds.
    offchainAddr, err := client.NewOffchainAddress(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Offchain address:", offchainAddr)

    // Check balance.
    balance, err := client.Balance(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Offchain balance: %d sats\n", balance.OffchainBalance.Total)

    // Send offchain.
    receivers := []clientTypes.Receiver{
        {To: "<recipient_offchain_addr>", Amount: 1000},
    }
    txid, err := client.SendOffChain(ctx, receivers)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Transaction ID:", txid)
}

Support

If you encounter any issues or have questions, please file an issue on our GitHub repository.

Name		Name	Last commit message	Last commit date
Latest commit History 113 Commits
.github		.github
api-spec/protobuf/gen/ark/v1		api-spec/protobuf/gen/ark/v1
store		store
test		test
types		types
.gitignore		.gitignore
.golangci.yml		.golangci.yml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
asset.go		asset.go
batch_session.go		batch_session.go
batch_session_opts.go		batch_session_opts.go
batch_session_opts_test.go		batch_session_opts_test.go
broadcaster.go		broadcaster.go
broadcaster_test.go		broadcaster_test.go
buf.Dockerfile		buf.Dockerfile
buf.gen.yaml		buf.gen.yaml
client.go		client.go
client_internal_test.go		client_internal_test.go
client_opts.go		client_opts.go
client_opts_test.go		client_opts_test.go
client_test.go		client_test.go
funding.go		funding.go
go.mod		go.mod
go.sum		go.sum
init.go		init.go
init_opts.go		init_opts.go
init_opts_test.go		init_opts_test.go
sdk.go		sdk.go
send.go		send.go
sync.go		sync.go
sync_test.go		sync_test.go
unroll.go		unroll.go
utils.go		utils.go
utils_test.go		utils_test.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Arkade Go SDK

Installation

Usage

1. Setting up the Ark Client

2. Client Configuration Options

3. Wallet Operations

Unlock and Lock the Wallet

Receive Funds

Check Balance

Send Offchain

Submit Transaction

Asset Operations

Issue Asset

Reissue Asset

Burn Asset

4. Advanced Usage

Multiple Recipients

Settle

Cooperative Exit

5. Additional Client Functions

6. Transport Client

Testing

Full Example

Support

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Arkade Go SDK

Installation

Usage

1. Setting up the Ark Client

2. Client Configuration Options

3. Wallet Operations

Unlock and Lock the Wallet

Receive Funds

Check Balance

Send Offchain

Submit Transaction

Asset Operations

Issue Asset

Reissue Asset

Burn Asset

4. Advanced Usage

Multiple Recipients

Settle

Cooperative Exit

5. Additional Client Functions

6. Transport Client

Testing

Full Example

Support

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages