@arkade-os/sdk 0.4.22 → 0.4.23

package/dist/types/repositories/serialization.d.ts

@@ -1,17 +1,33 @@
 import { TapLeafScript } from "../script/base";
-import { ExtendedCoin, ExtendedVirtualCoin } from "../wallet";
+import { ArkTransaction, Asset, ExtendedCoin, ExtendedVirtualCoin } from "../wallet";
 export type SerializedTapLeaf = {
     cb: string;
     s: string;
 };
 export type SerializedVtxo = ReturnType<typeof serializeVtxo>;
 export type SerializedUtxo = ReturnType<typeof serializeUtxo>;
+export type SerializedTransaction = ReturnType<typeof serializeTransaction>;
+export type SerializedAsset = {
+    assetId: string;
+    amount: string;
+};
 export declare const serializeTapLeaf: ([cb, s,]: TapLeafScript) => SerializedTapLeaf;
+export declare const serializeAsset: (a: Asset) => SerializedAsset;
+export declare const deserializeAsset: (a: {
+    assetId: string;
+    amount: string | number | bigint;
+}) => Asset;
+export declare const serializeAssets: (assets: Asset[] | undefined) => SerializedAsset[] | undefined;
+export declare const deserializeAssets: (assets: Array<{
+    assetId: string;
+    amount: string | number | bigint;
+}> | undefined) => Asset[] | undefined;
 export declare const serializeVtxo: (v: ExtendedVirtualCoin) => {
     tapTree: string;
     forfeitTapLeafScript: SerializedTapLeaf;
     intentTapLeafScript: SerializedTapLeaf;
     extraWitness: string[] | undefined;
+    assets: SerializedAsset[] | undefined;
     virtualStatus: import("../wallet").VirtualStatus;
     spentBy?: string;
     settledBy?: string;
@@ -19,7 +35,6 @@ export declare const serializeVtxo: (v: ExtendedVirtualCoin) => {
     createdAt: Date;
     isUnrolled: boolean;
     isSpent?: boolean;
-    assets?: import("../wallet").Asset[];
     script: string;
     value: number;
     status: import("../wallet").Status;
@@ -36,6 +51,15 @@ export declare const serializeUtxo: (u: ExtendedCoin) => {
     txid: string;
     vout: number;
 };
+export declare const serializeTransaction: (t: ArkTransaction) => {
+    assets: SerializedAsset[] | undefined;
+    key: import("../wallet").TxKey;
+    type: import("../wallet").TxType;
+    amount: number;
+    settled: boolean;
+    createdAt: number;
+};
 export declare const deserializeTapLeaf: (t: SerializedTapLeaf) => TapLeafScript;
 export declare const deserializeVtxo: (o: SerializedVtxo) => ExtendedVirtualCoin;
 export declare const deserializeUtxo: (o: SerializedUtxo) => ExtendedCoin;
+export declare const deserializeTransaction: (o: SerializedTransaction) => ArkTransaction;

package/dist/types/script/address.d.ts

@@ -43,7 +43,7 @@ export declare class ArkAddress {
      * @defaultValue `version = 0`
      * @throws Error if either public key is not 32 bytes long
      */
-    constructor(serverPubKey: Bytes, vtxoTaprootKey: Bytes, hrp: string, version?: number);
+    constructor(serverPubKey: Bytes, vtxoTaprootKey: Bytes, hrp?: string, version?: number);
     /**
      * Decode an Arkade address from its bech32m string form.
      *

package/dist/types/wallet/hdDescriptorProvider.d.ts

@@ -0,0 +1,93 @@
+import { DescriptorProvider, DescriptorSigningRequest } from "../identity/descriptorProvider";
+import { HDCapableIdentity } from "../identity/hdCapableIdentity";
+import { WalletRepository } from "../repositories/walletRepository";
+import { Transaction } from "../utils/transaction";
+/**
+ * HD-wallet {@link DescriptorProvider} that allocates a fresh signing
+ * descriptor on every call. The provider holds no notion of "current" — it
+ * is a pure rotating allocator. The question of "which descriptor is the
+ * wallet currently bound to?" is answered by querying the contract
+ * repository for active contracts, not by asking this provider.
+ *
+ * State is persisted under `WalletRepository.getWalletState().settings.hd` so
+ * that no storage-schema migration is required when switching a wallet from
+ * single-key to HD. The provider is backed by an {@link HDCapableIdentity},
+ * which carries the wildcard account descriptor template (for derivation)
+ * and the signing primitives.
+ *
+ * The read-modify-write of the persisted index runs inside the shared per-
+ * repo `updateWalletState` mutex, so two `getNextSigningDescriptor` callers
+ * — including those driving separate `HDDescriptorProvider` instances on
+ * the same repo — can never observe the same index.
+ *
+ * @example
+ * ```ts
+ * const provider = await HDDescriptorProvider.create(identity, walletRepo);
+ * const descriptor = await provider.getNextSigningDescriptor();
+ * // descriptor: tr([fp/86'/0'/0']xpub/0/0)
+ * const next = await provider.getNextSigningDescriptor();
+ * // next: tr([fp/86'/0'/0']xpub/0/1)
+ * ```
+ */
+export declare class HDDescriptorProvider implements DescriptorProvider {
+    private readonly identity;
+    private readonly walletRepository;
+    private constructor();
+    /**
+     * Construct an HDDescriptorProvider. No I/O is performed here;
+     * persisted state is read lazily on the first call to
+     * `getNextSigningDescriptor`. A descriptor-mismatch error surfaces on
+     * first use rather than at boot.
+     */
+    static create(identity: HDCapableIdentity, walletRepository: WalletRepository): Promise<HDDescriptorProvider>;
+    /**
+     * Allocate the next descriptor and return it. The first call on a fresh
+     * wallet returns descriptor at index 0; subsequent calls return 1, 2, 3,
+     * ... in order. Each call is atomic with respect to other rotations on
+     * the same repo: two concurrent callers can never observe the same
+     * index.
+     */
+    getNextSigningDescriptor(): Promise<string>;
+    /**
+     * Returns true when the given descriptor is derivable from this wallet's
+     * seed. Delegates to the underlying identity, which handles both HD and
+     * simple `tr(pubkey)` descriptors.
+     */
+    isOurs(descriptor: string): boolean;
+    /**
+     * Signs each request with the key derived from its descriptor. Delegates
+     * to the identity's signing primitives — the identity, not the provider,
+     * holds the seed.
+     */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /** Signs a message using the key derived from `descriptor`. */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+    /**
+     * Substitute the wildcard in the identity's account-descriptor template
+     * with a concrete index, going through the descriptors-scure parser
+     * rather than ad-hoc string substitution. The parser's `expand({ index })`
+     * call validates that the input is a ranged template AND produces a
+     * canonical materialized key expression at the given index.
+     */
+    private materializeAt;
+    /**
+     * Run the read-modify-write of HD settings inside the shared per-repo
+     * wallet-state mutex. The closure receives a freshly-validated settings
+     * snapshot, mutates it, and returns whatever value the caller wants to
+     * surface; the mutated settings are then persisted as part of the same
+     * atomic update.
+     *
+     * Doing the read inside the lock is what prevents two providers (or two
+     * concurrent callers on the same provider) from racing on a stale index.
+     */
+    private mutate;
+    /**
+     * Validate the persisted HD settings (or initialize a fresh record when
+     * absent) and return a clone safe for the caller to mutate.
+     *
+     * The cast to `HDWalletSettings` trusts storage; a corrupted or
+     * partially-migrated repo could otherwise produce `NaN` descriptors.
+     * Fail loud rather than silently derive garbage.
+     */
+    private parseSettings;
+}

package/dist/types/wallet/index.d.ts

@@ -11,6 +11,10 @@ import { ContractRepository, WalletRepository } from "../repositories";
 import { IContractManager } from "../contracts/contractManager";
 import { IDelegatorManager } from "./delegator";
 import { DelegatorProvider } from "../providers/delegator";
+/** Defaults */
+export declare const DEFAULT_ARKADE_SERVER_URL: "https://arkade.computer";
+export declare const DEFAULT_ARKADE_HRP = "ark";
+export declare const DEFAULT_NETWORK_NAME = "bitcoin";
 /**
  * Base configuration options shared by all wallet types.
  *
@@ -22,9 +26,6 @@ import { DelegatorProvider } from "../providers/delegator";
  * Provider-based configuration supplies concrete provider instances directly,
  * including the ArkProvider, IndexerProvider, OnchainProvider, and DelegatorProvider.
  *
- * At least one of the following must be provided:
- * - arkServerUrl OR arkProvider
- *
  * The wallet will use provided URLs to create default providers if custom provider
  * instances are not supplied. If optional parameters are not provided, the wallet
  * will fetch configuration from the Arkade server.
@@ -255,8 +256,12 @@ export interface SendBitcoinParams {
 export interface Asset {
     /** Asset identifier. */
     assetId: string;
-    /** Asset amount in base units. */
-    amount: number;
+    /**
+     * Asset amount in base units. Typed as `bigint` because asset
+     * supplies routinely exceed `Number.MAX_SAFE_INTEGER` (2^53 - 1)
+     * and silently truncating in arithmetic would corrupt balances.
+     */
+    amount: bigint;
 }
 /**
  * Recipient accepted by `IWallet.send`.
@@ -310,8 +315,12 @@ export type AssetMetadata = KnownMetadata & Record<string, unknown>;
 export type AssetDetails = {
     /** Asset identifier. */
     assetId: string;
-    /** Total issued supply in base units. */
-    supply: number;
+    /**
+     * Total issued supply in base units. Typed as `bigint` for the
+     * same reason as {@link Asset.amount} — supplies often exceed
+     * `Number.MAX_SAFE_INTEGER`.
+     */
+    supply: bigint;
     /** Optional immutable metadata associated with the asset. */
     metadata?: AssetMetadata;
     /** Optional control asset id required for future reissuance. */
@@ -325,7 +334,7 @@ export type AssetDetails = {
  */
 export interface IssuanceParams {
     /** Initial amount of asset to issue */
-    amount: number;
+    amount: bigint;
     /** Optional control asset ID that can be used for future reissuance */
     controlAssetId?: string;
     /** Immutable asset metadata including `ticker`, `decimals`, `icon` */
@@ -352,7 +361,7 @@ export interface ReissuanceParams {
     /** Existing asset ID, made up of genesis (Arkade) transaction ID and zero-based asset group index */
     assetId: string;
     /** Amount of asset to issue */
-    amount: number;
+    amount: bigint;
 }
 /**
  * Parameters accepted by `IAssetManager.burn`.
@@ -363,7 +372,7 @@ export interface BurnParams {
     /** Existing asset ID, made up of genesis (Arkade) transaction ID and zero-based asset group index */
     assetId: string;
     /** Amount of asset to burn */
-    amount: number;
+    amount: bigint;
 }
 /**
  * Explicit inputs and outputs accepted by `IWallet.settle`.

package/dist/types/wallet/onchain.d.ts

@@ -39,7 +39,7 @@ export declare class OnchainWallet implements AnchorBumper {
      * @defaultValue `provider = new EsploraProvider('https://mempool.space/api')`
      * @throws Error if the configured identity cannot produce a valid x-only public key
      */
-    static create(identity: Identity, networkName: NetworkName, provider?: OnchainProvider): Promise<OnchainWallet>;
+    static create(identity: Identity, networkName?: NetworkName, provider?: OnchainProvider): Promise<OnchainWallet>;
     get address(): string;
     /**
      * Fetch spendable onchain outputs for the wallet address.

package/dist/types/wallet/serviceWorker/wallet.d.ts

@@ -45,7 +45,7 @@ interface ServiceWorkerWalletOptions {
     /** Optional Arkade server public key used to construct and validate Arkade addresses. */
     arkServerPublicKey?: string;
     /** Base URL of the Arkade server. */
-    arkServerUrl: string;
+    arkServerUrl?: string;
     /** Optional override for the indexer URL. */
     indexerUrl?: string;
     /** Optional override for the Esplora API URL. */

package/dist/types/wallet/wallet.d.ts

@@ -19,6 +19,9 @@ import { DelegatorProvider } from "../providers/delegator";
 import { DelegateVtxo } from "../script/delegate";
 import { IDelegatorManager } from "./delegator";
 import { ContractManager } from "../contracts/contractManager";
+export declare const getArkadeServerUrl: ({ arkServerUrl, }: {
+    arkServerUrl?: string;
+}) => string;
 export type IncomingFunds = {
     type: "utxo";
     coins: Coin[];
@@ -321,7 +324,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
      * const txid = await wallet.send({
      *     address: 'ark1q...',
      *     amount: 1000, // (optional, default to dust) btc amount to send to the output
-     *     assets: [{ assetId: 'abc123...', amount: 50 }] // (optional) list of assets to send
+     *     assets: [{ assetId: 'abc123...', amount: 50n }] // (optional) list of assets to send
      * });
      * ```
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.22",
+  "version": "0.4.23",
   "description": "TypeScript SDK for building Bitcoin wallets using the Arkade protocol",
   "type": "module",
   "main": "./dist/cjs/index.js",