arklabshq/ark-sdk-client-init

SDK Client Initialization for Ark

When to Use

Use this skill when:

• Setting up a new Ark client (ArkClient)
• Configuring wallet types (SingleKey)
• Choosing transport types (gRPC, REST)
• Setting up storage backends (File, InMemory, KV, SQL)
• Managing wallet lifecycle (init, lock, unlock)
• Connecting to an Ark server (arkd)

Key Concepts

1. ArkClient Interface

The main entry point for all SDK operations:

type ArkClient interface {
    // Initialization
    Init(ctx context.Context, args InitArgs) error
    InitWithWallet(ctx context.Context, args InitWithWalletArgs) error

    // Wallet management
    IsLocked(ctx context.Context) bool
    Unlock(ctx context.Context, password string) error
    Lock(ctx context.Context) error

    // Balance and addresses
    Balance(ctx context.Context) (*Balance, error)
    Receive(ctx context.Context) (onchainAddr, offchainAddr, boardingAddr string, err error)

    // Transactions
    SendOffChain(ctx context.Context, receivers []types.Receiver, opt ...Option) (string, error)
    Settle(ctx context.Context, opts ...Option) (string, error)
    CollaborativeExit(ctx context.Context, addr string, amount uint64, opts ...Option) (string, error)
    // ... more methods
}

2. Client Types

| Type | Constant | Use Case | |------|----------|----------| | gRPC | GrpcClient | Recommended, better performance, streaming | | REST | RestClient | Simpler, HTTP-based, easier debugging |

3. Wallet Types

| Type | Constant | Description | |------|----------|-------------| | SingleKey | SingleKeyWallet | Single private key for all operations |

4. Store Types

| Type | Constant | Description | |------|----------|-------------| | InMemory | InMemoryStore | Ephemeral, lost on restart | | File | FileStore | Persistent, file-based storage | | KV | KVStore | Key-value database | | SQL | SQLStore | SQL database backend |

Code Patterns

Pattern 1: InitArgs Structure

type InitArgs struct {
    ClientType           string        // "grpc" or "rest"
    WalletType           string        // "singlekey"
    ServerUrl            string        // arkd server URL
    Seed                 string        // Private key hex (optional, generates if empty)
    Password             string        // Wallet encryption password
    ExplorerURL          string        // Blockchain explorer URL
    ExplorerPollInterval time.Duration // How often to poll explorer
    WithTransactionFeed  bool          // Enable real-time notifications
}

Source: go-sdk/types.go:24-33

Pattern 2: InitWithWalletArgs Structure

type InitWithWalletArgs struct {
    ClientType           string
    Wallet               wallet.WalletService  // Pre-configured wallet
    ServerUrl            string
    Seed                 string
    Password             string
    ExplorerURL          string
    ExplorerPollInterval time.Duration
    ExplorerBatchSize    uint32
    ExplorerBatchDelay   time.Duration
    WithTransactionFeed  bool
}

Source: go-sdk/types.go:66-77

Pattern 3: Creating a New Client with File Store

import (
    arksdk "github.com/arkade-os/go-sdk"
    filestore "github.com/arkade-os/go-sdk/store/file"
)

func createClient(datadir string) (arksdk.ArkClient, error) {
    // Create file-based store
    store, err := filestore.NewStore(datadir)
    if err != nil {
        return nil, err
    }

    // Create client with store
    client, err := arksdk.New(store)
    if err != nil {
        return nil, err
    }

    return client, nil
}

Pattern 4: Initializing the Client

func initClient(client arksdk.ArkClient, serverUrl, password string) error {
    ctx := context.Background()

    // Check if already initialized
    cfg, _ := client.GetConfigData(ctx)
    if cfg != nil {
        return arksdk.ErrAlreadyInitialized
    }

    // Initialize with args
    err := client.Init(ctx, arksdk.InitArgs{
        ClientType:          arksdk.GrpcClient,
        WalletType:          arksdk.SingleKeyWallet,
        ServerUrl:           serverUrl,
        Password:            password,
        WithTransactionFeed: true,  // Enable notifications
    })
    if err != nil {
        return err
    }

    // Unlock the wallet to start using it
    return client.Unlock(ctx, password)
}

Pattern 5: Restoring from Seed

func restoreFromSeed(client arksdk.ArkClient, serverUrl, password, seed string) error {
    ctx := context.Background()

    err := client.Init(ctx, arksdk.InitArgs{
        ClientType:          arksdk.GrpcClient,
        WalletType:          arksdk.SingleKeyWallet,
        ServerUrl:           serverUrl,
        Password:            password,
        Seed:                seed,  // Existing private key hex
        WithTransactionFeed: true,
    })
    if err != nil {
        return err
    }

    return client.Unlock(ctx, password)
}

Pattern 6: Available Constants

const (
    // Transport types
    GrpcClient = client.GrpcClient  // "grpc"
    RestClient = client.RestClient  // "rest"

    // Wallet types
    SingleKeyWallet = wallet.SingleKeyWallet  // "singlekey"

    // Store types
    FileStore     = types.FileStore      // "file"
    InMemoryStore = types.InMemoryStore  // "inmemory"

    // Explorer types
    BitcoinExplorer = mempool_explorer.BitcoinExplorer
)

Source: go-sdk/base_client.go:28-39

Pattern 7: Client Options

type ClientOption func(*arkClient)

// Enable verbose logging
func WithVerbose() ClientOption

// Enable periodic db refresh (for transaction feed)
func WithRefreshDb(interval time.Duration) ClientOption

// Disable auto-finalization of pending txs
func WithoutFinalizePendingTxs() ClientOption

Source: go-sdk/base_client.go:46-67

Pattern 8: Creating Client with Options

store, _ := filestore.NewStore(datadir)
client, _ := arksdk.New(store,
    arksdk.WithVerbose(),
    arksdk.WithRefreshDb(30*time.Second),
)

Pattern 9: Wallet Lock/Unlock Flow

func manageWallet(client arksdk.ArkClient, password string) error {
    ctx := context.Background()

    // Check if locked
    if client.IsLocked(ctx) {
        // Unlock to use
        if err := client.Unlock(ctx, password); err != nil {
            return err
        }
    }

    // Wait for sync if using transaction feed
    syncCh := client.IsSynced(ctx)
    if syncCh != nil {
        event := <-syncCh
        if event.Err != nil {
            return event.Err
        }
    }

    // ... do operations ...

    // Lock when done (optional)
    return client.Lock(ctx)
}

Source: go-sdk/base_client.go:106-203

Pattern 10: Getting Config After Init

func checkConfig(client arksdk.ArkClient) error {
    ctx := context.Background()

    cfg, err := client.GetConfigData(ctx)
    if err != nil {
        return err
    }

    // Access server info
    fmt.Printf("Server: %s\n", cfg.ServerUrl)
    fmt.Printf("Network: %s\n", cfg.Network.Name)
    fmt.Printf("Signer PubKey: %x\n", cfg.SignerPubKey.SerializeCompressed())
    fmt.Printf("Exit Delay: %d blocks\n", cfg.UnilateralExitDelay.Value)
    fmt.Printf("Dust: %d sats\n", cfg.Dust)

    return nil
}

Source: go-sdk/base_client.go:99-104

Pattern 11: Transaction Feed Channels

func subscribeToEvents(client arksdk.ArkClient) {
    ctx := context.Background()

    // VTXO events (new, spent, updated)
    vtxoCh := client.GetVtxoEventChannel(ctx)
    go func() {
        for event := range vtxoCh {
            switch event.Type {
            case types.VtxosAdded:
                fmt.Println("New VTXOs received")
            case types.VtxosSpent:
                fmt.Println("VTXOs spent")
            case types.VtxosUpdated:
                fmt.Println("VTXOs updated")
            }
        }
    }()

    // UTXO events (onchain)
    utxoCh := client.GetUtxoEventChannel(ctx)
    go func() {
        for event := range utxoCh {
            // Handle onchain events
        }
    }()

    // Transaction events
    txCh := client.GetTransactionEventChannel(ctx)
    go func() {
        for event := range txCh {
            // Handle transaction events
        }
    }()
}

Source: go-sdk/base_client.go:279-304

Pattern 12: Cleanup and Stop

func cleanup(client arksdk.ArkClient) {
    ctx := context.Background()

    // Reset: cleans store, stops all services
    client.Reset(ctx)

    // Or just stop: keeps data, stops services
    client.Stop()
}

Source: go-sdk/base_client.go:313-358

File References

| Purpose | File | Key Types/Functions | |---------|------|---------------------| | Client interface | go-sdk/ark_sdk.go | ArkClient interface | | Client implementation | go-sdk/base_client.go | arkClient, Init, Unlock, Lock | | Init args | go-sdk/types.go | InitArgs, InitWithWalletArgs, Balance | | SDK types | go-sdk/types/types.go | Config, Vtxo, Utxo, Receiver | | Wallet interface | go-sdk/wallet/wallet.go | WalletService | | SingleKey wallet | go-sdk/wallet/singlekey/bitcoin_wallet.go | bitcoinWallet | | File store | go-sdk/store/file/store.go | NewStore | | gRPC client | go-sdk/client/grpc/client.go | NewClient | | REST client | go-sdk/client/rest/client.go | NewClient |

Common Operations

Operation 1: Full Initialization Flow

// 1. Create store
store, _ := filestore.NewStore("~/.ark-wallet")

// 2. Create client
client, _ := arksdk.New(store, arksdk.WithVerbose())

// 3. Initialize (connects to server, creates wallet)
client.Init(ctx, arksdk.InitArgs{
    ClientType:          arksdk.GrpcClient,
    WalletType:          arksdk.SingleKeyWallet,
    ServerUrl:           "localhost:7070",
    Password:            "secure-password",
    WithTransactionFeed: true,
})

// 4. Unlock wallet
client.Unlock(ctx, "secure-password")

// 5. Wait for sync
<-client.IsSynced(ctx)

// 6. Ready to use!
balance, _ := client.Balance(ctx)

Operation 2: Check and Resume Existing Wallet

cfg, err := client.GetConfigData(ctx)
if err != nil {
    // Not initialized, need to init
    return client.Init(ctx, args)
}

// Already initialized, just unlock
if client.IsLocked(ctx) {
    return client.Unlock(ctx, password)
}
return nil

Operation 3: Export Wallet Seed

if !client.IsLocked(ctx) {
    seed, err := client.Dump(ctx)
    if err != nil {
        return err
    }
    fmt.Printf("Backup your seed: %s\n", seed)
}

Balance Structure

type Balance struct {
    OnchainBalance  OnchainBalance
    OffchainBalance OffchainBalance
}

type OnchainBalance struct {
    SpendableAmount uint64
    LockedAmount    []LockedOnchainBalance  // With CSV delays
}

type OffchainBalance struct {
    Total          uint64
    NextExpiration string      // When first VTXO expires
    Details        []VtxoDetails  // Per-expiration breakdown
}

Source: go-sdk/types.go:100-124

Gotchas & Edge Cases

1. Always Unlock After Init: The wallet is locked after Init(). You must call Unlock() before using other methods.

2. Wait for Sync: If WithTransactionFeed: true, wait for IsSynced() before querying balance. Otherwise you get stale data.

3. Password Required: Password cannot be empty. It's used to encrypt the wallet data.

4. Server Info: Client fetches server info (signer key, fees, delays) during Init(). Changing server requires re-init.

5. Store Persistence: InMemoryStore loses all data on restart. Use FileStore for production.

6. Transaction Feed: Without WithTransactionFeed, balance queries hit the server each time (slower but no background sync).

7. Reset vs Stop: Reset() cleans data, Stop() preserves it. Use Reset() for fresh start, Stop() for temporary shutdown.

8. Seed Format: Seed is hex-encoded private key (64 chars). Don't confuse with BIP39 mnemonic.

9. Lock Before Exit: Always call Lock() or Stop() before exiting to ensure clean shutdown.

10. Multiple Clients: Don't create multiple clients with same datadir - they'll conflict. Use single instance.

---

Skill Owner: ark-developer Repos: go-sdk