@arkade-os/sdk 0.4.14 → 0.4.16

package/README.md

@@ -1,8 +1,8 @@
 # Arkade TypeScript SDK
 
-The Arkade SDK is a TypeScript library for building Bitcoin wallets with support for both on-chain and off-chain transactions via the Ark protocol.
+The Arkade SDK is a TypeScript library for building Bitcoin wallets using the Arkade protocol.
 
-[![TypeScript Documentation](https://img.shields.io/badge/TypeScript-Documentation-blue?style=flat-square)](https://arkade-os.github.io/ts-sdk/)
+[![TypeDoc](https://img.shields.io/badge/TypeScript-Documentation-blue?style=flat-square)](https://arkade-os.github.io/ts-sdk/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/arkade-os/ts-sdk)
 
 ## Installation
@@ -19,52 +19,43 @@ npm install @arkade-os/sdk
 import {
   MnemonicIdentity,
   Wallet,
-  IndexedDBWalletRepository,
-  IndexedDBContractRepository
 } from '@arkade-os/sdk'
 import { generateMnemonic } from '@scure/bip39'
 import { wordlist } from '@scure/bip39/wordlists/english.js'
 
 // Generate a new mnemonic or use an existing one
 const mnemonic = generateMnemonic(wordlist)
-const identity = MnemonicIdentity.fromMnemonic(mnemonic, { isMainnet: false })
+const identity = MnemonicIdentity.fromMnemonic(mnemonic)
 
-// Create a wallet with Ark support
+// Create a wallet with Arkade support
 const wallet = await Wallet.create({
   identity,
-  // Esplora API, can be left empty - mempool.space API will be used
-  esploraUrl: 'https://mutinynet.com/api',
-  arkServerUrl: 'https://mutinynet.arkade.sh',
-  // Optional: provide repositories for persistence (defaults to IndexedDB)
-  // storage: {
-  //   walletRepository: new IndexedDBWalletRepository('my-wallet-db'),
-  //   contractRepository: new IndexedDBContractRepository('my-wallet-db')
-  // }
+  arkServerUrl: 'https://arkade.computer',
 })
 ```
 
-### Readonly Wallets (Watch-Only)
+### Read-Only Wallets (Watch-Only)
 
-The SDK supports readonly wallets that allow you to query wallet state without exposing private keys. This is useful for:
+The SDK supports read-only wallets that allow you to query wallet state without exposing private keys. This is useful for:
 
 - **Watch-only wallets**: Monitor addresses and balances without transaction capabilities
 - **Public interfaces**: Display wallet information safely in public-facing applications
 - **Separate concerns**: Keep signing operations isolated from query operations
 
-#### Creating a Readonly Wallet
+#### Creating a Read-Only Wallet
 
 ```typescript
-import { ReadonlySingleKey, ReadonlyWallet } from '@arkade-os/sdk'
+import { SingleKey, ReadonlySingleKey, ReadonlyWallet } from '@arkade-os/sdk'
 
-// Create a readonly identity from a public key
-const identity = SingleKey.fromHex('your_public_key_hex')
+// Create a read-only identity from a public key
+const identity = SingleKey.fromHex('e09ca...56609')
 const publicKey = await identity.compressedPublicKey()
 const readonlyIdentity = ReadonlySingleKey.fromPublicKey(publicKey)
 
-// Create a readonly wallet
+// Create a read-only wallet
 const readonlyWallet = await ReadonlyWallet.create({
   identity: readonlyIdentity,
-  arkServerUrl: 'https://mutinynet.arkade.sh'
+  arkServerUrl: 'https://arkade.computer'
 })
 
 // Query operations work normally
@@ -74,43 +65,43 @@ const vtxos = await readonlyWallet.getVtxos()
 const history = await readonlyWallet.getTransactionHistory()
 
 // Transaction methods are not available (TypeScript will prevent this)
-// await readonlyWallet.sendBitcoin(...) // ❌ Type error!
+// await readonlyWallet.send(...) // ❌ Type error!
 ```
 
-#### Converting Wallets to Readonly
+#### Converting Wallets to Read-Only
 
 ```typescript
-import { Wallet, SingleKey } from '@arkade-os/sdk'
+import { Wallet, MnemonicIdentity } from '@arkade-os/sdk'
 
 // Create a full wallet
-const identity = SingleKey.fromHex('your_private_key_hex')
+const identity = MnemonicIdentity.fromMnemonic('abandon abandon...')
 const wallet = await Wallet.create({
   identity,
-  arkServerUrl: 'https://mutinynet.arkade.sh'
+  arkServerUrl: 'https://arkade.computer'
 })
 
-// Convert to readonly wallet (safe to share)
+// Convert to read-only wallet (safe to share)
 const readonlyWallet = await wallet.toReadonly()
 
-// The readonly wallet can query but not transact
+// The read-only wallet can query but not transact
 const balance = await readonlyWallet.getBalance()
 ```
 
-#### Converting Identity to Readonly
+#### Converting Identity to Read-Only
 
 ```typescript
-import { SingleKey } from '@arkade-os/sdk'
+import { MnemonicIdentity } from '@arkade-os/sdk'
 
 // Full identity
-const identity = SingleKey.fromHex('your_private_key_hex')
+const identity = MnemonicIdentity.fromMnemonic('abandon abandon...')
 
-// Convert to readonly (no signing capability)
+// Convert to read-only (no signing capability)
 const readonlyIdentity = await identity.toReadonly()
 
-// Use in readonly wallet
+// Use in read-only wallet
 const readonlyWallet = await ReadonlyWallet.create({
   identity: readonlyIdentity,
-  arkServerUrl: 'https://mutinynet.arkade.sh'
+  arkServerUrl: 'https://arkade.computer'
 })
 ```
 
@@ -131,18 +122,17 @@ import { wordlist } from '@scure/bip39/wordlists/english.js'
 const mnemonic = generateMnemonic(wordlist)
 
 // Create identity from a 12 or 24 word mnemonic
-const identity = MnemonicIdentity.fromMnemonic(mnemonic, { isMainnet: true })
+const identity = MnemonicIdentity.fromMnemonic(mnemonic)
 
 // With optional passphrase for additional security
 const identityWithPassphrase = MnemonicIdentity.fromMnemonic(mnemonic, {
-  isMainnet: true,
   passphrase: 'my secret passphrase'
 })
 
 // Create wallet as usual
 const wallet = await Wallet.create({
-  identity,
-  arkServerUrl: 'https://mutinynet.arkade.sh'
+  identity: identityWithPassphrase,
+  arkServerUrl: 'https://arkade.computer'
 })
 ```
 
@@ -154,13 +144,13 @@ import { mnemonicToSeedSync } from '@scure/bip39'
 
 // If you already have a 64-byte seed
 const seed = mnemonicToSeedSync(mnemonic)
-const identity = SeedIdentity.fromSeed(seed, { isMainnet: true })
+const identity = SeedIdentity.fromSeed(seed)
 
 // Or with a custom output descriptor
-const identity2 = SeedIdentity.fromSeed(seed, { descriptor })
+const identityWithDescriptor = SeedIdentity.fromSeed(seed, { descriptor })
 
 // Or with a custom descriptor and passphrase (MnemonicIdentity)
-const identity3 = MnemonicIdentity.fromMnemonic(mnemonic, {
+const identityWithDescriptorAndPassphrase = MnemonicIdentity.fromMnemonic(mnemonic, {
   descriptor,
   passphrase: 'my secret passphrase'
 })
@@ -171,9 +161,13 @@ const identity3 = MnemonicIdentity.fromMnemonic(mnemonic, {
 Create watch-only wallets from an output descriptor:
 
 ```typescript
-import { ReadonlyDescriptorIdentity, ReadonlyWallet } from '@arkade-os/sdk'
+import { MnemonicIdentity, ReadonlyDescriptorIdentity, ReadonlyWallet } from '@arkade-os/sdk'
+import { generateMnemonic } from '@scure/bip39'
+import { wordlist } from '@scure/bip39/wordlists/english.js'
 
 // From a full identity
+const mnemonic = generateMnemonic(wordlist)
+const identity = MnemonicIdentity.fromMnemonic(mnemonic)
 const readonly = await identity.toReadonly()
 
 // Or directly from a descriptor (e.g., from another wallet)
@@ -183,7 +177,7 @@ const readonlyFromDescriptor = ReadonlyDescriptorIdentity.fromDescriptor(descrip
 // Use in a watch-only wallet
 const readonlyWallet = await ReadonlyWallet.create({
   identity: readonly,
-  arkServerUrl: 'https://mutinynet.arkade.sh'
+  arkServerUrl: 'https://arkade.computer'
 })
 
 // Can query but not sign
@@ -197,35 +191,71 @@ const balance = await readonlyWallet.getBalance()
 
 The descriptor format (`tr([fingerprint/path']xpub.../0/0)`) is HD-ready — future versions will support deriving multiple addresses and change outputs from the same seed.
 
+### Batch Signing for Browser Wallets
+
+Arkade send transactions require N+1 PSBT signatures (N checkpoints + 1 main tx). With local identities like `SingleKey` or `SeedIdentity` this is invisible, but browser wallet extensions (Xverse, UniSat, OKX, etc.) show a confirmation popup per signature. The `BatchSignableIdentity` interface lets wallet providers reduce N+1 popups to a single batch confirmation.
+
+```typescript
+import {
+  BatchSignableIdentity,
+  SignRequest,
+  isBatchSignable,
+  Wallet
+} from '@arkade-os/sdk'
+
+// Implement the interface in your wallet provider
+class MyBrowserWallet implements BatchSignableIdentity {
+  // ... implement Identity methods (sign, signMessage, xOnlyPublicKey, etc.)
+
+  async signMultiple(requests: SignRequest[]): Promise<Transaction[]> {
+    // Convert all PSBTs to your wallet's batch signing API format
+    const psbts = requests.map(r => r.tx.toPSBT())
+    // Single wallet popup for all signatures
+    const signedPsbts = await myWalletExtension.signAllPSBTs(psbts)
+    return signedPsbts.map(psbt => Transaction.fromPSBT(psbt))
+  }
+}
+
+// The SDK automatically detects batch-capable identities
+const identity = new MyBrowserWallet()
+console.log(isBatchSignable(identity)) // true
+
+// Wallet.send() uses one popup instead of N+1
+const wallet = await Wallet.create({ identity, arkServerUrl: 'https://arkade.computer' })
+await wallet.send({ address: 'ark1q...', amount: 1000 })
+```
+
+Identities without `signMultiple` continue to work unchanged — each checkpoint is signed individually via `sign()`.
+
 ### Receiving Bitcoin
 
 ```typescript
 import { waitForIncomingFunds } from '@arkade-os/sdk'
 
 // Get wallet addresses
-const arkAddress = await wallet.getAddress()
+const arkadeAddress = await wallet.getAddress()
 const boardingAddress = await wallet.getBoardingAddress()
-console.log('Ark Address:', arkAddress)
-console.log('Boarding Address:', boardingAddress)
+console.log('Arkade Address:', arkadeAddress)
+console.log('Boarding (Mainnet) Address:', boardingAddress)
 
 const incomingFunds = await waitForIncomingFunds(wallet)
 if (incomingFunds.type === "vtxo") {
-  // Virtual coins received 
-  console.log("VTXOs: ", incomingFunds.vtxos)
+  // Virtual outputs received 
+  console.log("VTXOs: ", incomingFunds.newVtxos)
 } else if (incomingFunds.type === "utxo") {
-  // Boarding coins received
+  // Boarding inputs received
   console.log("UTXOs: ", incomingFunds.coins)
 }
 ```
 
 ### Onboarding
 
-Onboarding allows you to swap on-chain funds into VTXOs:
+Onboarding allows you to swap onchain funds into virtual outputs:
 
 ```typescript
 import { Ramps } from '@arkade-os/sdk'
 
-const onboardTxid = await new Ramps(wallet).onboard();
+const boardingTxId = await new Ramps(wallet).onboard();
 ```
 
 ### Checking Balance
@@ -240,105 +270,130 @@ console.log('Offchain Settled:', balance.settled)
 console.log('Offchain Preconfirmed:', balance.preconfirmed)
 console.log('Recoverable:', balance.recoverable)
 
-// Get virtual UTXOs (off-chain)
-const virtualCoins = await wallet.getVtxos()
+// Get virtual outputs (available for offchain spending)
+const vtxos = await wallet.getVtxos()
 
-// Get boarding UTXOs
-const boardingUtxos = await wallet.getBoardingUtxos()
+// Get boarding inputs
+const boardingInputs = await wallet.getBoardingUtxos()
 ```
 
 ### Sending Bitcoin
 
 ```typescript
-// Send bitcoin via Ark
-const txid = await wallet.sendBitcoin({
-  address: 'ark1qq4...', // ark address
-  amount: 50000,         // in satoshis
+// Send bitcoin instantly offchain
+const txid = await wallet.send({
+  address: 'ark1q...',  // arkade address
+  amount: 50_000,       // in satoshis
 })
 ```
 
 ### Assets (Issue, Reissue, Burn, Send)
 
-The wallet's `assetManager` lets you create and manage assets on Ark. `send` method supports sending assets.
+The wallet's `assetManager` lets you create and manage assets on Arkade. The `send` method supports sending assets.
 
 ```typescript
 // Issue a new asset (non-reissuable by default)
-const controlAssetIssuance = await wallet.assetManager.issue({
-  amount: 1000,
-  metadata: { name: 'My Token', ticker: 'MTK', decimals: 8 },
+const { assetId: controlAssetId } = await wallet.assetManager.issue({
+  amount: 1,
+  metadata: {
+    ticker: 'ctrl-MTK'
+  }
 })
 
-// Issue a new asset using the control asset as reference
-const assetIssuance = await wallet.assetManager.issue({
+// Issue a new asset referencing the control asset
+const { assetId } = await wallet.assetManager.issue({
   amount: 500,
-  controlAssetId: controlAssetIssuance.assetId,
+  controlAssetId,
+  metadata: {
+    ticker: 'MTK'
+  }
 })
 
-// Reissue more supply of the asset, need ownership of the control asset
-const reissuanceTxid = await wallet.assetManager.reissue({
-  assetId: assetIssuance.assetId,
+// Reissue more supply of the asset (requires ownership of the control asset)
+const reissuanceTxId = await wallet.assetManager.reissue({
+  assetId,
   amount: 500,
 })
 
 // Burn some of the asset
-const burnTxid = await wallet.assetManager.burn({
-  assetId: assetIssuance.assetId,
+const burnTxId = await wallet.assetManager.burn({
+  assetId,
   amount: 200,
 })
 
-// Send asset to another Ark address
-const sendTxid = await wallet.send({
-  address: 'ark1qq4...',
-  assets: [{ assetId: assetIssuance.assetId, amount: 100 }],
+// Send asset to another Arkade address
+const sendTxId = await wallet.send({
+  address: 'ark1q...',
+  assets: [{ assetId, amount: 100 }],
 })
+
+// Check remaining balance
+const { assets } = await wallet.getBalance()
+const assetBalance = assets.find(asset => asset.assetId === assetId)?.amount
 ```
 
-### Batch Settlements
+### Batch Settlement
 
-This can be used to move preconfirmed balances into finalized balances and to manually convert UTXOs and VTXOs.
+The `settle` method can be used to move preconfirmed balances into finalized balances and to manually convert onchain funds to virtual outputs.
 
 ```typescript
+// Fetch offchain preconfirmed outputs and onchain boarding inputs
+const [vtxos, boardingInputs] = await Promise.all([
+  wallet.getVtxos(),
+  wallet.getBoardingUtxos()
+])
+
 // For settling transactions
-const settleTxid = await wallet.settle({
-  inputs, // from getVtxos() or getBoardingUtxos()
+const settlementTxId = await wallet.settle({
+  inputs: [...vtxos, ...boardingInputs],
+  // Optional: specify a mainnet output
   outputs: [{
-    address: destinationAddress,
-    amount: BigInt(amount)
+    address: "bc1p...",
+    amount: 100_000n
   }]
 })
 ```
 
-### VTXO Management (Renewal & Recovery)
+### Virtual Output Management (Renewal & Recovery)
 
-VTXOs have an expiration time (batch expiry). The SDK provides the `VtxoManager` class to handle:
+Virtual outputs have an expiration time (batch expiry).
 
-- **Renewal**: Renew VTXOs before they expire to maintain unilateral control of the funds.
-- **Recovery**: Reclaim swept or expired VTXOs back to the wallet in case renewal window was missed.
-- **Boarding UTXO Sweep**: Sweep expired boarding UTXOs back to a fresh boarding address to restart the timelock.
+The SDK provides the `VtxoManager` class to handle:
+
+- **Renewal**: Renew virtual outputs before they expire to maintain unilateral control of the funds.
+- **Recovery**: Reclaim swept or expired virtual outputs back to the wallet in case renewal window was missed.
+- **Boarding Input Sweep**: Sweep expired boarding inputs back to a fresh boarding address to restart the timelock.
 
 #### Settlement Configuration
 
 The recommended way to configure `VtxoManager` is via `settlementConfig` on the wallet.
 If you omit `settlementConfig`, settlement is enabled with the default behavior:
-VTXO renewal at 3 days and boarding UTXO sweep enabled.
+Virtual output renewal at 3 days and boarding input sweep enabled.
 
 ```typescript
 const wallet = await Wallet.create({
   identity,
-  arkServerUrl: 'https://mutinynet.arkade.sh',
-  // Enable settlement with defaults explicitly
-  settlementConfig: {},
+  arkServerUrl: 'https://arkade.computer',
+  // Enable settlement with defaults explicitly:
+  settlementConfig: {
+    // Seconds before virtual output expiry to trigger renewal
+    vtxoThreshold: 60 * 60 * 24 * 3, // 3 days
+    // Whether to sweep expired boarding inputs back to a fresh boarding address
+    boardingUtxoSweep: true,
+    // Polling interval in milliseconds for checking boarding inputs
+    pollIntervalMs: 60_000 // 1 minute
+  },
 })
 ```
 
 ```typescript
-// Enable both VTXO renewal and boarding UTXO sweep
+// Enable both virtual output renewal and boarding input sweep
 const wallet = await Wallet.create({
   identity,
-  arkServerUrl: 'https://mutinynet.arkade.sh',
+  arkServerUrl: 'https://arkade.computer',
   settlementConfig: {
-    vtxoThreshold: 86400,      // renew when 24 hours remain (in seconds)
-    boardingUtxoSweep: true,   // sweep expired boarding UTXOs
+    vtxoThreshold: 60 * 60 * 24,  // renew when 24 hours remain (in seconds)
+    boardingUtxoSweep: true,      // sweep expired boarding inputs
   },
 })
 ```
@@ -347,68 +402,60 @@ const wallet = await Wallet.create({
 // Explicitly disable all settlement
 const wallet = await Wallet.create({
   identity,
-  arkServerUrl: 'https://mutinynet.arkade.sh',
+  arkServerUrl: 'https://arkade.computer',
   settlementConfig: false,
 })
 ```
 
-Create the `VtxoManager` by passing the wallet and its settlement config:
+Access the `VtxoManager` from the wallet after configuring `settlementConfig`:
 
 ```typescript
-import { VtxoManager } from '@arkade-os/sdk'
-
-const manager = new VtxoManager(
-  wallet,
-  undefined,               // deprecated renewalConfig
-  wallet.settlementConfig  // new settlementConfig
-)
+const manager = await wallet.getVtxoManager()
 ```
 
-> **Migration from `renewalConfig`:** The old `renewalConfig` with `enabled` and `thresholdMs` (milliseconds) is still supported but deprecated. If both are provided, `settlementConfig` takes precedence. The new `vtxoThreshold` uses **seconds** instead of milliseconds.
+> **Migration from `renewalConfig`:** Directly initializing a `VtxoManager` with `renewalConfig` is still supported but deprecated. Prefer `settlementConfig` where `vtxoThreshold` is expressed in **seconds** instead of milliseconds.
 
 #### Renewal: Prevent Expiration
 
-Renew VTXOs before they expire to retain unilateral control of funds.
-This settles expiring and recoverable VTXOs back to your wallet, refreshing their expiration time.
+Renew virtual outputs before they expire to retain unilateral control of funds.
+This settles expiring and recoverable virtual outputs back to your wallet, refreshing their expiration time.
 
 ```typescript
-// Renew all VTXOs to prevent expiration
+// Renew all virtual outputs to prevent expiration
 const txid = await manager.renewVtxos()
-console.log('Renewed:', txid)
-
-// Check which VTXOs are expiring soon
+// Check which virtual outputs are expiring soon
 const expiringVtxos = await manager.getExpiringVtxos()
-// Override thresholdMs (e.g., renew when 5 seconds of time remains)
-const urgentlyExpiring = await manager.getExpiringVtxos(5_000)
+// Override thresholdMs (e.g., get virtual outputs expiring in the next 60 seconds)
+const urgentlyExpiring = await manager.getExpiringVtxos(60_000)
 ```
 
-#### Boarding UTXO Sweep
+#### Boarding Input Sweep
 
-When a boarding UTXO's CSV timelock expires, it can no longer be onboarded into Ark cooperatively. The sweep feature detects these expired UTXOs and builds a raw on-chain transaction that spends them via the unilateral exit path back to a fresh boarding address, restarting the timelock.
+When a boarding input's CSV timelock expires, it can no longer be onboarded into Arkade cooperatively. The sweep feature detects these expired UTXOs and builds a raw onchain transaction that spends them via the unilateral exit path back to a fresh boarding address, restarting the timelock.
 
 - Multiple expired UTXOs are batched into a single transaction (many inputs, one output)
 - A dust check ensures the sweep is skipped if fees would consume the entire value
 
 ```typescript
-// Check for expired boarding UTXOs
+// Check for expired boarding inputs
 const expired = await manager.getExpiredBoardingUtxos()
-console.log(`${expired.length} expired boarding UTXOs`)
+console.log(`${expired.length} expired boarding inputs`)
 
 // Sweep them back to a fresh boarding address (requires boardingUtxoSweep: true)
 try {
   const txid = await manager.sweepExpiredBoardingUtxos()
-  console.log('Swept expired boarding UTXOs:', txid)
+  console.log('Swept expired boarding inputs:', txid)
 } catch (e) {
-  // "No expired boarding UTXOs to sweep" or "Sweep not economical"
+  // "No expired boarding inputs to sweep" or "Sweep not economical"
 }
 ```
 
 #### Recovery: Reclaim Swept VTXOs
 
-Recover VTXOs that have been swept by the server or consolidate small amounts (subdust).
+Recover virtual outputs that have been swept by the server or consolidate small amounts (subdust).
 
 ```typescript
-// Recover swept VTXOs and preconfirmed subdust
+// Recover swept virtual outputs and preconfirmed subdust
 const txid = await manager.recoverVtxos((event) => {
   console.log('Settlement event:', event.type)
 })
@@ -418,71 +465,79 @@ const balance = await manager.getRecoverableBalance()
 ```
 
 
-### VTXO Delegation
+### Delegation
+
+Delegation allows users to outsource virtual output renewal to a third-party delegation service.
+
+Instead of the delegating user renewing virtual outputs by themself, their delegate will automatically settle them before they expire, sending the funds back to the delegator's wallet address (minus a service fee).
+
+This is useful for wallets that cannot be online 24/7.
 
-Delegation allows you to outsource VTXO renewal to a third-party delegator service. Instead of renewing VTXOs yourself, the delegator will automatically settle them before they expire, sending the funds back to your wallet address (minus a service fee). This is useful for wallets that cannot be online 24/7.
+When a `delegatorProvider` is configured, the wallet address includes an extra tapscript path that authorizes the delegate to co-sign renewals alongside the Arkade server.
 
-When a `delegatorProvider` is configured, the wallet address includes an extra tapscript path that authorizes the delegator to co-sign renewals alongside the Ark server.
+To run a delegation service, you'll need to set up a [Fulmine server](https://github.com/ArkLabsHQ/fulmine) with the [Delegation API](https://github.com/ArkLabsHQ/fulmine?tab=readme-ov-file#-delegate-api) enabled.
 
 #### Setting Up a Wallet with Delegation
 
 ```typescript
-import { Wallet, SingleKey, RestDelegatorProvider } from '@arkade-os/sdk'
-
-const identity = SingleKey.fromHex('your_private_key_hex')
+import { Wallet, MnemonicIdentity, RestDelegatorProvider } from '@arkade-os/sdk'
 
 const wallet = await Wallet.create({
-  identity,
-  arkServerUrl: 'https://mutinynet.arkade.sh',
-  delegatorProvider: new RestDelegatorProvider('https://delegator.example.com'),
+  identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+  arkServerUrl: 'https://arkade.computer',
+  delegatorProvider: new RestDelegatorProvider('http://localhost:7001'),
 })
 ```
 
 > **Note:** Adding a `delegatorProvider` changes your wallet address because the offchain tapscript includes an additional delegation path. Funds sent to an address without delegation cannot be delegated, and vice versa.
 
-#### Delegating VTXOs
+#### Delegating Virtual Outputs
 
-Once the wallet is configured with a delegator, use `wallet.delegatorManager` to delegate your VTXOs:
+Once the wallet is configured with a delegate, use `wallet.delegatorManager` to delegate your virtual outputs:
 
 ```typescript
-// Get spendable VTXOs
-const vtxos = (await wallet.getVtxos({ withRecoverable: true }))
-  .filter(v => v.virtualStatus.type === 'confirmed')
+// Get spendable virtual outputs (including recoverable)
+const vtxos = await wallet.getVtxos({ withRecoverable: true })
 
-// Delegate all VTXOs — the delegator will renew them before expiry
-const myAddress = await wallet.getAddress()
-const result = await wallet.delegatorManager.delegate(vtxos, myAddress)
+// Delegate all virtual outputs — the delegate will renew them before expiry
+const arkadeAddress = await wallet.getAddress()
+const delegatorManager = await wallet.getDelegatorManager();
+const delegationResult = await delegatorManager.delegate(vtxos, arkadeAddress)
 
-console.log('Delegated:', result.delegated.length)
-console.log('Failed:', result.failed.length)
+console.log('Delegated:', delegationResult.delegated.length)
+console.log('Failed:', delegationResult.failed.length)
 ```
 
-The `delegate` method groups VTXOs by expiry date and submits them to the delegator service. By default, delegation is scheduled at 90% of each VTXO's remaining lifetime. You can override this with an explicit date:
+The `delegate` method groups virtual outputs by expiry date and submits them to the delegation service.
+
+By default, delegation is scheduled at 90% of each virtual output's remaining lifetime.
+
+You can override this with an explicit date:
 
 ```typescript
 // Delegate with a specific renewal time
 const delegateAt = new Date(Date.now() + 12 * 60 * 60 * 1000) // 12 hours from now
-await wallet.delegatorManager.delegate(vtxos, myAddress, delegateAt)
+await delegatorManager.delegate(vtxos, arkadeAddress, delegateAt)
 ```
 
 #### Service Worker Integration
 
-When using a service worker wallet, pass the `delegatorUrl` option. The service worker will automatically delegate VTXOs after each VTXO update:
+When using a service worker wallet, pass the `delegatorUrl` option. The service worker will automatically delegate virtual outputs after each update:
 
 ```typescript
-import { ServiceWorkerWallet, SingleKey } from '@arkade-os/sdk'
+import { ServiceWorkerWallet, MnemonicIdentity } from '@arkade-os/sdk'
 
 const wallet = await ServiceWorkerWallet.setup({
   serviceWorkerPath: '/service-worker.js',
-  arkServerUrl: 'https://mutinynet.arkade.sh',
-  identity: SingleKey.fromHex('your_private_key_hex'),
-  delegatorUrl: 'https://delegator.example.com',
+  arkServerUrl: 'https://arkade.computer',
+  identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+  delegatorUrl: 'http://localhost:7001',
 })
 ```
 
-#### Querying Delegator Info
+#### Querying Delegate Info
 
-You can query the delegator service directly to inspect its public key, fee, and payment address:
+You can query the delegation service directly to inspect its public key, fee, and payment address:
 
 ```typescript
 import { RestDelegatorProvider } from '@arkade-os/sdk'
@@ -490,7 +545,7 @@ import { RestDelegatorProvider } from '@arkade-os/sdk'
 const provider = new RestDelegatorProvider('https://delegator.example.com')
 const info = await provider.getDelegateInfo()
 
-console.log('Delegator public key:', info.pubkey)
+console.log('Delegate public key:', info.pubkey)
 console.log('Service fee (sats):', info.fee)
 console.log('Fee address:', info.delegatorAddress)
 ```
@@ -500,9 +555,9 @@ console.log('Fee address:', info.delegatorAddress)
 Sign and verify messages using [BIP-322](https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki). Supports P2TR (Taproot) signing, and verification for P2TR, P2WPKH, and legacy P2PKH addresses.
 
 ```typescript
-import { BIP322, SingleKey } from '@arkade-os/sdk'
+import { BIP322, MnemonicIdentity } from '@arkade-os/sdk'
 
-const identity = SingleKey.fromHex('your_private_key_hex')
+const identity = MnemonicIdentity.fromMnemonic('abandon abandon...')
 
 // Sign a message (P2TR key-spend)
 const signature = await BIP322.sign('Hello Bitcoin!', identity)
@@ -520,44 +575,66 @@ BIP322.verify('Hello Bitcoin!', sig, '1A1zP1...')  // legacy P2PKH
 ```typescript
 // Get transaction history
 const history = await wallet.getTransactionHistory()
+/*
+{
+    key: {
+        boardingTxid: string;
+        commitmentTxid: string;
+        arkTxid: string;
+    };
+    type: "SENT" | "RECEIVED";
+    amount: number;
+    settled: boolean;
+    createdAt: number;
+    assets?: Array<{
+        assetId: string,
+        amount: number
+    }>
+}
+*/
 ```
 
 ### Offboarding
 
-Collaborative exit or "offboarding" allows you to withdraw your virtual funds to an on-chain address:
+Collaborative exit or "offboarding" allows you to withdraw your virtual funds to an onchain address:
 
 ```typescript
-import { Ramps } from '@arkade-os/sdk'
+import { Wallet, MnemonicIdentity, Ramps } from '@arkade-os/sdk'
+
+const wallet = await Wallet.create({
+  identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+  arkServerUrl: 'https://arkade.computer'
+})
 
 // Get fee information from the server
-const info = await wallet.arkProvider.getInfo();
+const { fees: feeInfo } = await wallet.arkProvider.getInfo();
 
 const exitTxid = await new Ramps(wallet).offboard(
-  onchainAddress,
-  info.fees
+  'bc1p...',
+  feeInfo
 );
 ```
 
 ### Unilateral Exit
 
-Unilateral exit allows you to withdraw your funds from the Ark protocol back to the Bitcoin blockchain without requiring cooperation from the Ark server. This process involves two main steps:
+Unilateral exit allows you to withdraw your funds from the Arkade protocol back to the Bitcoin blockchain without requiring cooperation from the Arkade server. This process involves two main steps:
 
-1. **Unrolling**: Broadcasting the transaction chain from off-chain back to on-chain
-2. **Completing the exit**: Spending the unrolled VTXOs after the timelock expires
+1. **Unrolling**: Broadcasting the transaction chain from offchain back to onchain
+2. **Completing the exit**: Spending the unrolled virtual outputs after the timelock expires
 
-#### Step 1: Unrolling VTXOs
+#### Step 1: Unrolling Virtual Outputs
 
 ```typescript
-import { Unroll, OnchainWallet, SingleKey } from '@arkade-os/sdk'
+import { MnemonicIdentity, OnchainWallet, Unroll } from '@arkade-os/sdk'
 
 // Create an identity for the onchain wallet
-const onchainIdentity = SingleKey.fromHex('your_onchain_private_key_hex');
+const onchainIdentity = MnemonicIdentity.fromMnemonic('abandon abandon...')
 
-// Create an onchain wallet to pay for P2A outputs in VTXO branches
+// Create an onchain wallet to pay for P2A outputs in virtual output branches
 // OnchainWallet implements the AnchorBumper interface
 const onchainWallet = await OnchainWallet.create(onchainIdentity, 'regtest');
 
-// Unroll a specific VTXO
+// Unroll a specific virtual output
 const vtxo = { txid: 'your_vtxo_txid', vout: 0 };
 const session = await Unroll.Session.create(
   vtxo,
@@ -576,7 +653,7 @@ for await (const step of session) {
       console.log(`Broadcasting transaction ${step.tx.id}`);
       break;
     case Unroll.StepType.DONE:
-      console.log(`Unrolling complete for VTXO ${step.vtxoTxid}`);
+      console.log(`Unrolling complete for virtual output ${step.vtxoTxid}`);
       break;
   }
 }
@@ -585,29 +662,29 @@ for await (const step of session) {
 The unrolling process works by:
 
 - Traversing the transaction chain from the root (most recent) to the leaf (oldest)
-- Broadcasting each transaction that isn't already on-chain
+- Broadcasting each transaction that isn't already onchain
 - Waiting for confirmations between steps
 - Using P2A (Pay-to-Anchor) transactions to pay for fees
 
 #### Step 2: Completing the Exit
 
-Once VTXOs are fully unrolled and the unilateral exit timelock has expired, you can complete the exit:
+Once virtual outputs are fully unrolled and the unilateral exit timelock has expired, you can complete the exit:
 
 ```typescript
-// Complete the exit for specific VTXOs
+// Complete the exit for specific virtual outputs
 await Unroll.completeUnroll(
   wallet,
-  [vtxo.txid], // Array of VTXO transaction IDs to complete
+  [vtxo.txid], // Array of virtual output transaction IDs to complete
   onchainWallet.address // Address to receive the exit amount
 );
 ```
 
 **Important Notes:**
 
-- Each VTXO may require multiple unroll steps depending on the transaction chain length
+- Each virtual output may require multiple unroll steps depending on the transaction chain length
 - Each unroll step must be confirmed before proceeding to the next
-- The `completeUnroll` method can only be called after VTXOs are fully unrolled and the timelock has expired
-- You need sufficient on-chain funds in the `OnchainWallet` to pay for P2A transaction fees
+- The `completeUnroll` method can only be called after all virtual outputs are fully unrolled and the timelock has expired
+- You need sufficient onchain funds in the `OnchainWallet` to pay for P2A transaction fees
 
 ### Running the wallet in a service worker
 
@@ -643,15 +720,13 @@ bus.start()
 
 ```typescript
 // app.ts
-import { ServiceWorkerWallet, SingleKey } from '@arkade-os/sdk'
-
-const identity = SingleKey.fromHex('your_private_key_hex')
+import { ServiceWorkerWallet, MnemonicIdentity } from '@arkade-os/sdk'
 
 // One-liner: registers the SW, initializes the MessageBus, and creates the wallet
 const wallet = await ServiceWorkerWallet.setup({
   serviceWorkerPath: '/service-worker.js',
-  arkServerUrl: 'https://mutinynet.arkade.sh',
-  identity,
+  arkServerUrl: 'https://arkade.computer',
+  identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
 })
 
 // Use like any other wallet — calls are proxied to the service worker
@@ -677,12 +752,9 @@ differ in orchestration and communication.
 See the platform READMEs for architecture details, runtime flow, and usage
 examples.
 
-
-
 ### Repositories (Storage)
 
-The `StorageAdapter` API is deprecated. Use repositories instead. If you omit
-`storage`, the SDK uses IndexedDB repositories with the default database name.
+The `StorageAdapter` API is deprecated. Use repositories instead. If you omit `storage`, the SDK uses IndexedDB repositories with the default database name.
 
 #### Migration from v1 StorageAdapter
 
@@ -778,7 +850,7 @@ See [examples/node/multiple-wallets.ts](examples/node/multiple-wallets.ts) for
 a full working example using `better-sqlite3`.
 
 ```typescript
-import { SingleKey, Wallet } from '@arkade-os/sdk'
+import { MnemonicIdentity, Wallet } from '@arkade-os/sdk'
 import { SQLiteWalletRepository, SQLiteContractRepository, SQLExecutor } from '@arkade-os/sdk/repositories/sqlite'
 import Database from 'better-sqlite3'
 
@@ -792,8 +864,8 @@ const executor: SQLExecutor = {
 }
 
 const wallet = await Wallet.create({
-  identity: SingleKey.fromHex('your_private_key_hex'),
-  arkServerUrl: 'https://mutinynet.arkade.sh',
+  identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+  arkServerUrl: 'https://arkade.computer',
   storage: {
     walletRepository: new SQLiteWalletRepository(executor),
     contractRepository: new SQLiteContractRepository(executor),
@@ -811,7 +883,7 @@ import { RealmWalletRepository, RealmContractRepository, ArkRealmSchemas } from
 const realm = await Realm.open({ schema: [...ArkRealmSchemas, ...yourSchemas] })
 const wallet = await Wallet.create({
   identity,
-  arkServerUrl: 'https://mutinynet.arkade.sh',
+  arkServerUrl: 'https://arkade.computer',
   storage: {
     walletRepository: new RealmWalletRepository(realm),
     contractRepository: new RealmContractRepository(realm),
@@ -825,11 +897,11 @@ In the browser, the SDK defaults to IndexedDB repositories when no `storage`
 is provided:
 
 ```typescript
-import { SingleKey, Wallet } from '@arkade-os/sdk'
+import { MnemonicIdentity, Wallet } from '@arkade-os/sdk'
 
 const wallet = await Wallet.create({
-  identity: SingleKey.fromHex('your_private_key_hex'),
-  arkServerUrl: 'https://mutinynet.arkade.sh',
+  identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+  arkServerUrl: 'https://arkade.computer',
   // Uses IndexedDB by default in the browser
 })
 ```
@@ -841,14 +913,15 @@ For ephemeral storage (no persistence), pass the in-memory repositories:
 
 ```typescript
 import {
+  MnemonicIdentity,
+  Wallet,
   InMemoryWalletRepository,
-  InMemoryContractRepository,
-  Wallet
+  InMemoryContractRepository
 } from '@arkade-os/sdk'
 
 const wallet = await Wallet.create({
-  identity,
-  arkServerUrl: 'https://mutinynet.arkade.sh',
+  identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+  arkServerUrl: 'https://arkade.computer',
   storage: {
     walletRepository: new InMemoryWalletRepository(),
     contractRepository: new InMemoryContractRepository()
@@ -869,7 +942,7 @@ import { EventSource } from "eventsource";
 (globalThis as any).EventSource = EventSource;
 
 // Use dynamic import so the polyfill is set before the SDK evaluates
-const { Wallet, SingleKey, Ramps } = await import("@arkade-os/sdk");
+const { Wallet } = await import("@arkade-os/sdk");
 ```
 
 If you also need IndexedDB persistence (e.g. for `WalletRepository`), set up the shim before any SDK import:
@@ -895,16 +968,15 @@ See [`examples/node/multiple-wallets.ts`](examples/node/multiple-wallets.ts) for
 For React Native and Expo applications where standard EventSource and fetch streaming may not work properly, use the Expo-compatible providers:
 
 ```typescript
-import { Wallet, SingleKey } from '@arkade-os/sdk'
+import { Wallet, MnemonicIdentity } from '@arkade-os/sdk'
 import { ExpoArkProvider, ExpoIndexerProvider } from '@arkade-os/sdk/adapters/expo'
 
-const identity = SingleKey.fromHex('your_private_key_hex')
+const identity = MnemonicIdentity.fromMnemonic('abandon abandon...')
 
 const wallet = await Wallet.create({
   identity: identity,
-  esploraUrl: 'https://mutinynet.com/api',
-  arkProvider: new ExpoArkProvider('https://mutinynet.arkade.sh'), // For settlement events and transactions streaming
-  indexerProvider: new ExpoIndexerProvider('https://mutinynet.arkade.sh'), // For address subscriptions and VTXO updates
+  arkProvider: new ExpoArkProvider('https://arkade.computer'), // For settlement events and transactions streaming
+  indexerProvider: new ExpoIndexerProvider('https://arkade.computer'), // For address subscriptions and virtual output state updates
 })
 
 // use expo/fetch for streaming support (SSE)
@@ -916,7 +988,7 @@ const address = await wallet.getAddress()
 Both ExpoArkProvider and ExpoIndexerProvider are available as adapters following the SDK's modular architecture pattern. This keeps the main SDK bundle clean while providing opt-in functionality for specific environments:
 
 - **ExpoArkProvider**: Handles settlement events and transaction streaming using expo/fetch for Server-Sent Events
-- **ExpoIndexerProvider**: Handles address subscriptions and VTXO updates using expo/fetch for JSON streaming
+- **ExpoIndexerProvider**: Handles address subscriptions and virtual output state updates using expo/fetch for JSON streaming
 
 For persistence in Expo/React Native, use the SQLite repository with `expo-sqlite`:
 
@@ -933,9 +1005,9 @@ const executor = {
 
 const wallet = await Wallet.create({
   identity,
-  arkServerUrl: 'https://mutinynet.arkade.sh',
-  arkProvider: new ExpoArkProvider('https://mutinynet.arkade.sh'),
-  indexerProvider: new ExpoIndexerProvider('https://mutinynet.arkade.sh'),
+  arkServerUrl: 'https://arkade.computer',
+  arkProvider: new ExpoArkProvider('https://arkade.computer'),
+  indexerProvider: new ExpoIndexerProvider('https://arkade.computer'),
   storage: {
     walletRepository: new SQLiteWalletRepository(executor),
     contractRepository: new SQLiteContractRepository(executor),
@@ -958,7 +1030,7 @@ if (!global.crypto) global.crypto = {} as any;
 global.crypto.getRandomValues = Crypto.getRandomValues;
 
 // Now import the SDK
-import { Wallet, SingleKey } from '@arkade-os/sdk';
+import { Wallet, MnemonicIdentity } from '@arkade-os/sdk';
 import { ExpoArkProvider, ExpoIndexerProvider } from '@arkade-os/sdk/adapters/expo';
 ```
 
@@ -966,7 +1038,7 @@ This is required for MuSig2 settlements and cryptographic operations.
 
 ### Contract Management
 
-Both `Wallet` and `ServiceWorkerWallet` use a `ContractManager` internally to watch for VTXOs. This provides resilient connection handling with automatic reconnection and failsafe polling - for your wallet's default address and any external contracts you register (Boltz swaps, HTLCs, etc.).
+Both `Wallet` and `ServiceWorkerWallet` use a `ContractManager` internally to watch for virtual outputs. This provides resilient connection handling with automatic reconnection and failsafe polling - for your wallet's default address and any external contracts you register (Boltz swaps, HTLCs, etc.).
 
 When you call `wallet.notifyIncomingFunds()` or use `waitForIncomingFunds()`, it uses the ContractManager under the hood, giving you automatic reconnection and failsafe polling for free - no code changes needed.
 
@@ -997,10 +1069,10 @@ const contract = await manager.createContract({
 const unsubscribe = await manager.onContractEvent((event) => {
   switch (event.type) {
     case 'vtxo_received':
-      console.log(`Received ${event.vtxos.length} VTXOs on ${event.contractScript}`)
+      console.log(`Received ${event.vtxos.length} virtual outputs to ${event.contractScript}`)
       break
     case 'vtxo_spent':
-      console.log(`Spent VTXOs on ${event.contractScript}`)
+      console.log(`Spent virtual outputs from ${event.contractScript}`)
       break
     case 'contract_expired':
       console.log(`Contract ${event.contractScript} expired`)
@@ -1011,7 +1083,7 @@ const unsubscribe = await manager.onContractEvent((event) => {
 // Update contract data (e.g., set preimage when revealed)
 await manager.updateContractParams(contract.script, { preimage: revealedPreimage })
 
-// Check spendable paths (requires a specific VTXO)
+// Check spendable paths (requires a specific virtual output)
 const [withVtxos] = await manager.getContractsWithVtxos({ script: contract.script })
 const vtxo = withVtxos.vtxos[0]
 const paths = manager.getSpendablePaths({
@@ -1025,17 +1097,17 @@ if (paths.length > 0) {
 }
 
 // Or list all possible paths for the current context (no spendability checks)
-const allPaths = manager.getAllSpendingPaths({
+const allPaths = await manager.getAllSpendingPaths({
   contractScript: contract.script,
   collaborative: true,
   walletPubKey: myPubKey,
 })
 
-// Get balances across all contracts
-const balances = await manager.getAllBalances()
+// Fetch contracts together with their current virtual outputs
+const contractsWithVtxos = await manager.getContractsWithVtxos()
 
-// Manually sweep all eligible contracts
-const sweepResults = await manager.sweepAll()
+// Force a full refresh from the indexer when needed
+await manager.refreshVtxos()
 
 // Stop watching
 unsubscribe()
@@ -1051,7 +1123,7 @@ The watcher features:
 Access low-level data management through repositories:
 
 ```typescript
-// VTXO management (automatically cached for performance)
+// Virtual output management (automatically cached for performance)
 const addr = await wallet.getAddress()
 const vtxos = await wallet.walletRepository.getVtxos(addr)
 await wallet.walletRepository.saveVtxos(addr, vtxos)
@@ -1069,7 +1141,7 @@ await wallet.contractRepository.saveToContractCollection(
 const swaps = await wallet.contractRepository.getContractCollection('swaps')
 ```
 
-_For complete API documentation, visit our [TypeScript documentation](https://arkade-os.github.io/ts-sdk/)._
+_For complete API documentation, visit our [TypeDoc documentation](https://arkade-os.github.io/ts-sdk/)._
 
 ## Development