Smart Account Kit

Features

Installation

pnpm add smart-account-kit

Quick Start

import { SmartAccountKit, IndexedDBStorage } from 'smart-account-kit';
// Initialize the SDK
const kit = new SmartAccountKit({
 rpcUrl: 'https://soroban-testnet.stellar.org',
 networkPassphrase: 'Test SDF Network ; September 2015',
 accountWasmHash: 'YOUR_ACCOUNT_WASM_HASH',
 webauthnVerifierAddress: 'CWEBAUTHN_VERIFIER_ADDRESS',
 storage: new IndexedDBStorage(),
});
// On page load - silent restore from stored session
const result = await kit.connectWallet();
if (!result) {
 // No stored session, show connect button
 showConnectButton();
}
// User clicks "Create Wallet"
const { contractId, credentialId } = await kit.createWallet('My App', 'user@example.com', {
 autoSubmit: true,
});
// User clicks "Connect Wallet" - prompts for passkey selection
await kit.connectWallet({ prompt: true });
// Sign and submit a transaction
const result = await kit.signAndSubmit(transaction);

Configuration

SmartAccountKit Options

Fee Sponsoring

const kit = new SmartAccountKit({
 // ... other config
 relayerUrl: 'https://my-relayer-proxy.example.com',
});
// Transactions automatically use the Relayer if configured
await kit.transfer(tokenContract, recipient, amount);
// To bypass the Relayer for specific operations
await kit.transfer(tokenContract, recipient, amount, { forceMethod: 'rpc' });

Storage Adapters

import {
 IndexedDBStorage, // Recommended for web apps
 LocalStorageAdapter, // Simple fallback
 MemoryStorage, // For testing
} from 'smart-account-kit';
// Use IndexedDB (recommended)
const storage = new IndexedDBStorage();
// Or implement your own
class MyStorage implements StorageAdapter {
 async save(credential: StoredCredential): Promise<void> { ... }
 async get(credentialId: string): Promise<StoredCredential | null> { ... }
 async saveSession(session: StoredSession): Promise<void> { ... }
 async getSession(): Promise<StoredSession | null> { ... }
 // ... other methods
}

API Reference

SmartAccountKit

import { SmartAccountKit } from 'smart-account-kit';

Core Methods

Wallet Lifecycle

Sub-Manager Properties

Usage Examples

// Create a new wallet
const { contractId, credentialId } = await kit.createWallet('My App', 'user@example.com', {
 autoSubmit: true, // Automatically deploy the wallet
 autoFund: true, // Fund via Friendbot (testnet only)
 nativeTokenContract: 'CDLZFC3...',
});
// Connect to existing wallet
const result = await kit.connectWallet(); // Silent restore from session
await kit.connectWallet({ prompt: true }); // Prompt user to select passkey
await kit.connectWallet({ fresh: true }); // Ignore session, always prompt
await kit.connectWallet({ credentialId: '...' }); // Connect with specific credential
await kit.connectWallet({ contractId: 'C...' }); // Connect with specific contract
// Transfer tokens
const result = await kit.transfer('CTOKEN...', 'GRECIPIENT...', 100);
// Build an arbitrary smart-account mediated call
const tx = await kit.execute('CTARGET...', 'set_config', [owner, threshold]);
// Or build + sign + submit in one step
const execResult = await kit.executeAndSubmit('CTARGET...', 'set_config', [owner, threshold]);
// Disconnect
await kit.disconnect();

Raw Wallet Escape Hatch

Sub-Managers

SignerManager (kit.signers)

// Add a new passkey signer
const { credentialId, transaction } = await kit.signers.addPasskey(
 0, // Context rule ID
 'My App', // App name
 'Recovery Key', // User name
 { nickname: 'Backup YubiKey' }
);
// Add a delegated signer (Stellar account)
await kit.signers.addDelegated(0, 'GABC...');
// Remove a signer by value; the SDK resolves signer IDs internally
await kit.signers.remove(0, signer);

ContextRuleManager (kit.rules)

// Add a new context rule
await kit.rules.add(contextType, 'Rule Name', signers, policies);
// Read a specific rule directly from chain
const rule = (await kit.rules.get(0)).result;
// Active rule discovery requires indexer access
const rules = await kit.rules.list();
const allRules = await kit.rules.getAll(contextType);

// Update rules
await kit.rules.updateName(0, 'New Name');
await kit.rules.updateExpiration(0, expirationLedger);
// Remove a rule
await kit.rules.remove(0);

PolicyManager (kit.policies)

// Add a policy
await kit.policies.add(0, 'CPOLICY...', installParams);
// Remove a policy
await kit.policies.remove(0, 'CPOLICY...');

CredentialManager (kit.credentials)

// Get credentials
const all = await kit.credentials.getAll();
const pending = await kit.credentials.getPending();
const walletCreds = await kit.credentials.getForWallet();
// Deploy a pending credential
const result = await kit.credentials.deploy('credential-id', { autoSubmit: true });
// Sync with on-chain state
await kit.credentials.syncAll();
// Delete a pending credential
await kit.credentials.delete('credential-id');

MultiSignerManager (kit.multiSigners)

// Get all available signers (requires indexer access)
const signers = await kit.multiSigners.getAvailableSigners();
// Check if multi-sig is needed
if (kit.multiSigners.needsMultiSigner(signers)) {
 // Build selected signers for transaction
 const selected = kit.multiSigners.buildSelectedSigners(signers, activeCredentialId);
 // Execute multi-sig transfer
 const result = await kit.multiSigners.transfer(
 'CTOKEN...',
 'GRECIPIENT...',
 '100',
 selected
 );
}

External Signer Support

import { ExternalSignerManager } from 'smart-account-kit';

ExternalSignerManager (kit.externalSigners)

// Add a keypair signer
kit.externalSigners.addFromSecret('SXXX...');
// Connect external wallet
await kit.externalSigners.addFromWallet(walletAdapter);
// Check signing capability
if (kit.externalSigners.canSignFor('GABC...')) {
 const signedEntry = await kit.externalSigners.signAuthEntry('GABC...', authEntry);
}

Types

Configuration Types

import type {
 SmartAccountConfig, // SDK initialization config
 PolicyConfig, // Policy contract config
 SubmissionOptions, // Transaction submission options
} from 'smart-account-kit';

Credential & Session Types

import type {
 StoredCredential, // Full credential metadata
 StoredSession, // Auto-reconnect session data
 CredentialDeploymentStatus, // "pending" | "failed"
 StorageAdapter, // Storage backend interface
} from 'smart-account-kit';

Result Types

import type {
 CreateWalletResult, // Wallet creation outcome
 ConnectWalletResult, // Connection outcome
 TransactionResult, // Transaction outcome (success/failure)
} from 'smart-account-kit';

External Wallet Types

import type {
 ExternalWalletAdapter, // Interface for wallet extensions
 ConnectedWallet, // Single wallet connection info
 SelectedSigner, // Signer selection for multi-sig
} from 'smart-account-kit';

Contract Types (from smart-account bindings)

import type {
 ContractSigner, // On-chain signer type (alias: Signer)
 ContextRule, // Context rule structure
 ContextRuleType, // Rule type enum
 AuthPayload, // Smart-account auth payload
 WebAuthnSigData, // WebAuthn signature format
 SimpleThresholdAccountParams, // M-of-N multisig params
 WeightedThresholdAccountParams, // Weighted voting params
 SpendingLimitAccountParams, // Time-limited spending params
} from 'smart-account-kit';

Builder Functions

Signer Builders

import {
 createDelegatedSigner, // Create Stellar account signer (G-address)
 createExternalSigner, // Create custom verifier signer
 createWebAuthnSigner, // Create passkey signer
 createEd25519Signer, // Create Ed25519 signer
} from 'smart-account-kit';
// Create a delegated signer
const signer = createDelegatedSigner('GABC...', 'ed25519-verifier-address');
// Create a WebAuthn signer
const passkeySigner = createWebAuthnSigner(verifierAddress, publicKey, credentialId);

Context Rule Type Builders

import {
 createDefaultContext, // Default rule (matches any operation)
 createCallContractContext, // Rule for specific contract calls
 createCreateContractContext, // Rule for contract deployments
} from 'smart-account-kit';
// Create a context for calling a specific contract
const context = createCallContractContext('CCONTRACT...');

Policy Parameter Builders

import {
 createThresholdParams, // M-of-N multisig
 createWeightedThresholdParams, // Weighted voting
 createSpendingLimitParams, // Time-limited spending
 LEDGERS_PER_HOUR, // ~720 ledgers
 LEDGERS_PER_DAY, // ~17,280 ledgers
 LEDGERS_PER_WEEK, // ~120,960 ledgers
} from 'smart-account-kit';
// Create 2-of-3 multisig params
const thresholdParams = createThresholdParams(2);
// Create spending limit params
const spendingParams = createSpendingLimitParams(
 'CTOKEN...', // Token contract
 BigInt(1000 * 10_000_000), // 1000 tokens in stroops
 LEDGERS_PER_DAY // Reset period
);

Signer Helper Functions

import {
 getCredentialIdFromSigner, // Extract credential ID from signer
 signersEqual, // Compare two signers
 truncateAddress, // Display helper
 formatSignerForDisplay, // Display helper
} from 'smart-account-kit';

Constants

import {
 WEBAUTHN_TIMEOUT_MS, // WebAuthn timeout (60000ms)
 BASE_FEE, // Transaction base fee
 STROOPS_PER_XLM, // 10,000,000
 FRIENDBOT_RESERVE_XLM, // Friendbot reserve amount
} from 'smart-account-kit';

Error Classes

import {
 SmartAccountError, // Base error class
 SmartAccountErrorCode, // Error codes enum
 WalletNotConnectedError, // No wallet connected
 CredentialNotFoundError, // Credential not found in storage
 SignerNotFoundError, // Signer not found on-chain
 SimulationError, // Transaction simulation failed
 SubmissionError, // Transaction submission failed
 ValidationError, // Input validation failed
 WebAuthnError, // WebAuthn operation failed
 SessionError, // Session management error
 wrapError, // Error wrapper utility
} from 'smart-account-kit';
// Error handling
try {
 await kit.transfer(...);
} catch (error) {
 if (error instanceof WalletNotConnectedError) {
 // Handle not connected
 } else if (error instanceof SimulationError) {
 // Handle simulation failure
 }
}

Event System

import { SmartAccountEventEmitter } from 'smart-account-kit';
import type { SmartAccountEventMap, SmartAccountEvent, EventListener } from 'smart-account-kit';

Available Events

// Listen to events
kit.events.on('walletConnected', ({ contractId }) => {
 console.log('Connected to:', contractId);
});
kit.events.on('transactionSubmitted', ({ hash, success }) => {
 console.log('Transaction:', hash, success ? 'succeeded' : 'failed');
});
// One-time listener
kit.events.once('walletConnected', handler);
// Remove listener
kit.events.off('walletConnected', handler);

Wallet Adapters

import { StellarWalletsKitAdapter } from 'smart-account-kit';
import type { StellarWalletsKitAdapterConfig } from 'smart-account-kit';
// Create adapter for StellarWalletsKit integration
const adapter = new StellarWalletsKitAdapter({
 kit: stellarWalletsKit,
 onConnectionChange: (connected) => {
 console.log('Wallet connection changed:', connected);
 },
});
// Use with external signers
await kit.externalSigners.addFromWallet(adapter);

Relayer Client

import {
 RelayerClient,
 RelayerErrorCodes,
} from 'smart-account-kit';
import type {
 RelayerResponse,
 RelayerSendOptions,
 RelayerErrorCode,
} from 'smart-account-kit';

Using via SmartAccountKit (Recommended)

const kit = new SmartAccountKit({
 // ... other config
 relayerUrl: 'https://my-relayer-proxy.example.com',
});
// Transactions automatically use the Relayer
await kit.transfer(tokenContract, recipient, amount);
// Bypass the Relayer for specific operations
await kit.transfer(tokenContract, recipient, amount, { forceMethod: 'rpc' });
// Access the Relayer client directly
if (kit.relayer) {
 const result = await kit.relayer.sendXdr(signedTransaction);
}

Using RelayerClient Directly

const relayer = new RelayerClient('https://my-relayer-proxy.example.com');
// Submit a transaction for fee sponsoring (func + auth)
const result = await relayer.send(funcXdr, authXdrs);
// Or submit a signed transaction for fee-bumping
const xdrResult = await relayer.sendXdr(signedTransaction);
if (result.success) {
 console.log('Transaction hash:', result.hash);
} else {
 console.error('Failed:', result.error, result.errorCode);
}

Indexer Client

import {
 IndexerClient,
 IndexerError,
 DEFAULT_INDEXER_URLS,
} from 'smart-account-kit';
import type {
 IndexerConfig,
 IndexedContractSummary,
 IndexedSigner,
 IndexedPolicy,
 IndexedContextRule,
 CredentialLookupResponse,
 AddressLookupResponse,
 ContractDetailsResponse,
 IndexerStatsResponse,
} from 'smart-account-kit';

Using via SmartAccountKit (Recommended)

// Indexer is auto-configured for testnet/mainnet
const kit = new SmartAccountKit({ /* config */ });
// Discover contracts by credential ID
const contracts = await kit.discoverContractsByCredential(credentialId);
// Discover contracts by address
const contracts = await kit.discoverContractsByAddress('GABC...');
// Get contract details
const details = await kit.getContractDetailsFromIndexer('CABC...');
// Or use the indexer client directly
if (kit.indexer) {
 const stats = await kit.indexer.getStats();
 const healthy = await kit.indexer.isHealthy();
}

Using IndexerClient Directly

// Create client for a known Stellar network
const indexer = IndexerClient.forNetwork('Test SDF Network ; September 2015');
const mainnetIndexer = IndexerClient.forNetwork('Public Global Stellar Network ; September 2015');
// Or with a custom URL
const indexer = new IndexerClient({
 baseUrl: 'https://smart-account-indexer.sdf-ecosystem.workers.dev',
 timeout: 10000,
});
// Lookup by credential ID
const { contracts } = await indexer.lookupByCredentialId(credentialIdHex);
// Lookup by address
const { contracts } = await indexer.lookupByAddress('GABC...');
// Get full contract details
const details = await indexer.getContractDetails('CABC...');

Re-exported Types

import type { AssembledTransaction } from 'smart-account-kit';

Building from Source

Prerequisites

Setup

# Clone the repository
git clone https://github.com/kalepail/smart-account-kit
cd smart-account-kit
# Configure demo environment (has testnet defaults)
cp demo/.env.example demo/.env
# Edit demo/.env if needed
# Install dependencies
pnpm install
# Build everything (generates bindings from network, builds packages)
pnpm run build:all

Environment Configuration

Getting Contract WASM Hashes

Build Commands

Publishing

# Ensure you're logged in to npm
npm login
# Bump version (updates package.json)
pnpm version patch # or minor, major
# Publish
pnpm publish
# Or publish with specific tag
pnpm publish --tag beta

Related

License