@1sat/wallet-toolbox 0.0.21 → 0.0.23

package/dist/api/constants.d.ts

@@ -15,6 +15,7 @@ export declare const ORDLOCK_PREFIX = "2097dfd76851bf465e8f715593b217714858bbe95
 export declare const ORDLOCK_SUFFIX = "615179547a75537a537a537a0079537a75527a527a7575615579008763567901c161517957795779210ac407f0e4bd44bfc207355a778b046225a7068fc59ee7eda43ad905aadbffc800206c266b30e6a1319c66dc401e5bd6b432ba49688eecd118297041da8074ce081059795679615679aa0079610079517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e01007e81517a75615779567956795679567961537956795479577995939521414136d08c5ed2bf3ba048afe6dcaebafeffffffffffffffffffffffffffffff00517951796151795179970079009f63007952799367007968517a75517a75517a7561527a75517a517951795296a0630079527994527a75517a6853798277527982775379012080517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f517f7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e7c7e01205279947f7754537993527993013051797e527e54797e58797e527e53797e52797e57797e0079517a75517a75517a75517a75517a75517a75517a75517a75517a75517a75517a75517a75517a756100795779ac517a75517a75517a75517a75517a75517a75517a75517a75517a7561517a75517a756169587951797e58797eaa577961007982775179517958947f7551790128947f77517a75517a75618777777777777777777767557951876351795779a9876957795779ac777777777777777767006868";
 export declare const LOCK_PREFIX = "20d37f4de0d1c735b4d51a5572df0f3d9104d1d9e99db8694fdd1b1a92e1f0dce1757601687f76a9";
 export declare const LOCK_SUFFIX = "88ac7e7601207f75a9011488";
+export declare const ONESAT_PROTOCOL: [0 | 1 | 2, string];
 export declare const MESSAGE_SIGNING_PROTOCOL: [0 | 1 | 2, string];
 export declare const MAX_INSCRIPTION_BYTES = 100000;
 export declare const MIN_UNLOCK_SATS = 1500;

package/dist/api/constants.js

@@ -21,7 +21,8 @@ export const ORDLOCK_SUFFIX = "615179547a75537a537a537a0079537a75527a527a7575615
 // Lock template constants
 export const LOCK_PREFIX = "20d37f4de0d1c735b4d51a5572df0f3d9104d1d9e99db8694fdd1b1a92e1f0dce1757601687f76a9";
 export const LOCK_SUFFIX = "88ac7e7601207f75a9011488";
-// Message signing protocol
+// Protocol IDs
+export const ONESAT_PROTOCOL = [1, "1sat"];
 export const MESSAGE_SIGNING_PROTOCOL = [1, "message signing"];
 // Constants
 export const MAX_INSCRIPTION_BYTES = 100_000;

package/dist/api/inscriptions/index.js

@@ -5,11 +5,7 @@
  */
 import { P2PKH, PublicKey, Script, Utils } from "@bsv/sdk";
 import { Inscription } from "@bopen-io/templates";
-import { MAX_INSCRIPTION_BYTES, ORDINALS_BASKET } from "../constants";
-// ============================================================================
-// Constants
-// ============================================================================
-const ORDINAL_PROTOCOL = [1, "ordinal"];
+import { MAX_INSCRIPTION_BYTES, ORDINALS_BASKET, ONESAT_PROTOCOL } from "../constants";
 // ============================================================================
 // Internal helpers
 // ============================================================================
@@ -58,7 +54,7 @@ export const inscribe = {
             }
             const keyID = Date.now().toString();
             const { publicKey } = await ctx.wallet.getPublicKey({
-                protocolID: ORDINAL_PROTOCOL,
+                protocolID: ONESAT_PROTOCOL,
                 keyID,
                 counterparty: "self",
                 forSelf: true,
@@ -75,7 +71,7 @@ export const inscribe = {
                         basket: ORDINALS_BASKET,
                         tags: [`type:${input.contentType}`],
                         customInstructions: JSON.stringify({
-                            protocolID: ORDINAL_PROTOCOL,
+                            protocolID: ONESAT_PROTOCOL,
                             keyID,
                         }),
                     },

package/dist/api/ordinals/index.js

@@ -6,18 +6,13 @@
  */
 import { BigNumber, Hash, LockingScript, OP, P2PKH, PublicKey, Script, Transaction, TransactionSignature, UnlockingScript, Utils, } from "@bsv/sdk";
 import { OrdLock } from "@bopen-io/templates";
-import { ORDINALS_BASKET, ORDLOCK_PREFIX, ORDLOCK_SUFFIX } from "../constants";
-// ============================================================================
-// Constants
-// ============================================================================
-const ORDINAL_PROTOCOL = [1, "ordinal"];
-const ORDINAL_LISTING_PROTOCOL = [1, "ordinal listing"];
+import { ORDINALS_BASKET, ORDLOCK_PREFIX, ORDLOCK_SUFFIX, ONESAT_PROTOCOL } from "../constants";
 // ============================================================================
 // Internal helpers
 // ============================================================================
 async function deriveCancelAddressInternal(ctx, outpoint) {
     const result = await ctx.wallet.getPublicKey({
-        protocolID: ORDINAL_LISTING_PROTOCOL,
+        protocolID: ONESAT_PROTOCOL,
         keyID: outpoint,
         forSelf: true,
     });
@@ -97,7 +92,7 @@ export async function buildTransferOrdinal(ctx, request) {
     let recipientAddress;
     if (counterparty) {
         const { publicKey } = await ctx.wallet.getPublicKey({
-            protocolID: ORDINAL_PROTOCOL,
+            protocolID: ONESAT_PROTOCOL,
             keyID: outpoint,
             counterparty,
             forSelf: false,
@@ -169,7 +164,7 @@ export async function buildListOrdinal(ctx, request) {
                 basket: ORDINALS_BASKET,
                 tags,
                 customInstructions: JSON.stringify({
-                    protocolID: ORDINAL_LISTING_PROTOCOL,
+                    protocolID: ONESAT_PROTOCOL,
                     keyID: outpoint,
                 }),
             },
@@ -248,7 +243,10 @@ export const transferOrdinal = {
             if ("error" in params) {
                 return params;
             }
-            const result = await ctx.wallet.createAction(params);
+            const result = await ctx.wallet.createAction({
+                ...params,
+                options: { randomizeOutputs: false },
+            });
             if (!result.txid) {
                 return { error: "no-txid-returned" };
             }
@@ -283,7 +281,10 @@ export const listOrdinal = {
             if ("error" in params) {
                 return params;
             }
-            const result = await ctx.wallet.createAction(params);
+            const result = await ctx.wallet.createAction({
+                ...params,
+                options: { randomizeOutputs: false },
+            });
             if (!result.txid) {
                 return { error: "no-txid-returned" };
             }
@@ -355,7 +356,7 @@ export const cancelListing = {
                         customInstructions: JSON.stringify({ protocolID, keyID }),
                     },
                 ],
-                options: { signAndProcess: false },
+                options: { signAndProcess: false, randomizeOutputs: false },
             });
             if ("error" in createResult && createResult.error) {
                 return { error: String(createResult.error) };
@@ -473,7 +474,7 @@ export const purchaseOrdinal = {
                 return { error: "not-an-ordlock-listing" };
             }
             const { publicKey } = await ctx.wallet.getPublicKey({
-                protocolID: ORDINAL_PROTOCOL,
+                protocolID: ONESAT_PROTOCOL,
                 keyID: outpoint,
                 counterparty: "self",
                 forSelf: true,
@@ -488,7 +489,7 @@ export const purchaseOrdinal = {
                 basket: ORDINALS_BASKET,
                 tags: [`type:${contentType}`, `origin:${origin}`],
                 customInstructions: JSON.stringify({
-                    protocolID: ORDINAL_PROTOCOL,
+                    protocolID: ONESAT_PROTOCOL,
                     keyID: outpoint,
                 }),
             });
@@ -523,7 +524,7 @@ export const purchaseOrdinal = {
                     },
                 ],
                 outputs,
-                options: { signAndProcess: false },
+                options: { signAndProcess: false, randomizeOutputs: false },
             });
             if ("error" in createResult && createResult.error) {
                 return { error: String(createResult.error) };

package/dist/api/sweep/index.d.ts

@@ -5,7 +5,7 @@
  */
 import type { OneSatContext, Skill } from "../skills/types";
 import type { IndexedOutput } from "../../services/types";
-import type { SweepBsvRequest, SweepBsvResponse, SweepInput } from "./types";
+import type { SweepBsvRequest, SweepBsvResponse, SweepInput, SweepOrdinalsRequest, SweepOrdinalsResponse } from "./types";
 export * from "./types";
 /**
  * Prepare sweep inputs from IndexedOutput objects by fetching locking scripts.
@@ -20,4 +20,11 @@ export declare function prepareSweepInputs(ctx: OneSatContext, utxos: IndexedOut
  * value is swept (minus fees).
  */
 export declare const sweepBsv: Skill<SweepBsvRequest, SweepBsvResponse>;
-export declare const sweepSkills: Skill<SweepBsvRequest, SweepBsvResponse>[];
+/**
+ * Sweep ordinals from external inputs into the destination wallet.
+ *
+ * Each input is expected to be a 1-sat ordinal output. Each ordinal is
+ * transferred to a derived address using the wallet's key derivation.
+ */
+export declare const sweepOrdinals: Skill<SweepOrdinalsRequest, SweepOrdinalsResponse>;
+export declare const sweepSkills: (Skill<SweepBsvRequest, SweepBsvResponse> | Skill<SweepOrdinalsRequest, SweepOrdinalsResponse>)[];

package/dist/api/sweep/index.js

@@ -3,7 +3,8 @@
  *
  * Functions for sweeping assets from external wallets into a BRC-100 wallet.
  */
-import { P2PKH, PrivateKey, Transaction, } from "@bsv/sdk";
+import { P2PKH, PrivateKey, PublicKey, Transaction, } from "@bsv/sdk";
+import { ONESAT_PROTOCOL } from "../constants";
 export * from "./types";
 /**
  * Prepare sweep inputs from IndexedOutput objects by fetching locking scripts.
@@ -217,5 +218,168 @@ export const sweepBsv = {
         }
     },
 };
+/**
+ * Sweep ordinals from external inputs into the destination wallet.
+ *
+ * Each input is expected to be a 1-sat ordinal output. Each ordinal is
+ * transferred to a derived address using the wallet's key derivation.
+ */
+export const sweepOrdinals = {
+    meta: {
+        name: "sweepOrdinals",
+        description: "Sweep ordinals from external wallet (via WIF) into the connected wallet",
+        category: "sweep",
+        requiresServices: true,
+        inputSchema: {
+            type: "object",
+            properties: {
+                inputs: {
+                    type: "array",
+                    description: "Ordinal UTXOs to sweep",
+                    items: {
+                        type: "object",
+                        properties: {
+                            outpoint: { type: "string", description: "Outpoint (txid_vout)" },
+                            satoshis: { type: "integer", description: "Satoshis (should be 1)" },
+                            lockingScript: { type: "string", description: "Locking script hex" },
+                            contentType: { type: "string", description: "Content type from metadata" },
+                            origin: { type: "string", description: "Origin outpoint" },
+                        },
+                        required: ["outpoint", "satoshis", "lockingScript"],
+                    },
+                },
+                wif: {
+                    type: "string",
+                    description: "WIF private key controlling the inputs",
+                },
+            },
+            required: ["inputs", "wif"],
+        },
+    },
+    async execute(ctx, request) {
+        if (!ctx.services) {
+            return { error: "services-required" };
+        }
+        try {
+            const { inputs, wif } = request;
+            if (!inputs || inputs.length === 0) {
+                return { error: "no-inputs" };
+            }
+            // Parse WIF
+            const privateKey = PrivateKey.fromWif(wif);
+            // Fetch BEEF for all input transactions and merge them
+            const txids = [...new Set(inputs.map((i) => i.outpoint.split("_")[0]))];
+            console.log(`[sweepOrdinals] Fetching BEEF for ${txids.length} transactions`);
+            const firstBeef = await ctx.services.getBeefForTxid(txids[0]);
+            for (let i = 1; i < txids.length; i++) {
+                const additionalBeef = await ctx.services.getBeefForTxid(txids[i]);
+                firstBeef.mergeBeef(additionalBeef);
+            }
+            console.log(`[sweepOrdinals] Merged BEEF valid=${firstBeef.isValid()}, txs=${firstBeef.txs.length}`);
+            // Build input descriptors
+            const inputDescriptors = inputs.map((input) => {
+                const [txid, voutStr] = input.outpoint.split("_");
+                return {
+                    outpoint: `${txid}.${voutStr}`,
+                    inputDescription: `Ordinal ${input.origin ?? input.outpoint}`,
+                    unlockingScriptLength: 108,
+                    sequenceNumber: 0xffffffff,
+                };
+            });
+            // Build outputs - one per ordinal, each 1 sat to derived address
+            const outputs = [];
+            for (const input of inputs) {
+                // Derive a unique public key for this ordinal using the input outpoint as keyID
+                const pubKeyResult = await ctx.wallet.getPublicKey({
+                    protocolID: ONESAT_PROTOCOL,
+                    keyID: input.outpoint,
+                    forSelf: true,
+                });
+                if (!pubKeyResult.publicKey) {
+                    return { error: `Failed to derive key for ${input.outpoint}` };
+                }
+                // Create P2PKH locking script from derived public key
+                const derivedAddress = PublicKey.fromString(pubKeyResult.publicKey).toAddress();
+                const lockingScript = new P2PKH().lock(derivedAddress);
+                // Build tags following ordinals API pattern
+                const tags = [];
+                if (input.contentType)
+                    tags.push(`type:${input.contentType}`);
+                if (input.origin)
+                    tags.push(`origin:${input.origin}`);
+                outputs.push({
+                    lockingScript: lockingScript.toHex(),
+                    satoshis: 1,
+                    outputDescription: `Ordinal ${input.origin ?? input.outpoint}`,
+                    basket: "1sat",
+                    tags,
+                    customInstructions: JSON.stringify({
+                        protocolID: ONESAT_PROTOCOL,
+                        keyID: input.outpoint,
+                    }),
+                });
+            }
+            const beefData = firstBeef.toBinary();
+            // Create action to get signable transaction
+            // CRITICAL: randomizeOutputs must be false to preserve ordinal satoshi positions
+            const createResult = await ctx.wallet.createAction({
+                description: `Sweep ${inputs.length} ordinal${inputs.length !== 1 ? "s" : ""}`,
+                inputBEEF: beefData,
+                inputs: inputDescriptors,
+                outputs,
+                options: { signAndProcess: false, randomizeOutputs: false },
+            });
+            if ("error" in createResult && createResult.error) {
+                return { error: String(createResult.error) };
+            }
+            if (!createResult.signableTransaction) {
+                return { error: "no-signable-transaction" };
+            }
+            // Sign each input with our external key
+            const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
+            // Build a set of outpoints we control
+            const ourOutpoints = new Set(inputs.map((input) => {
+                const [txid, vout] = input.outpoint.split("_");
+                return `${txid}.${vout}`;
+            }));
+            // Set up P2PKH unlocker on each input we control
+            for (let i = 0; i < tx.inputs.length; i++) {
+                const txInput = tx.inputs[i];
+                const inputOutpoint = `${txInput.sourceTXID}.${txInput.sourceOutputIndex}`;
+                if (ourOutpoints.has(inputOutpoint)) {
+                    const p2pkh = new P2PKH();
+                    txInput.unlockingScriptTemplate = p2pkh.unlock(privateKey, "all", true);
+                }
+            }
+            await tx.sign();
+            // Extract unlocking scripts for signAction
+            const spends = {};
+            for (let i = 0; i < tx.inputs.length; i++) {
+                const txInput = tx.inputs[i];
+                const inputOutpoint = `${txInput.sourceTXID}.${txInput.sourceOutputIndex}`;
+                if (ourOutpoints.has(inputOutpoint)) {
+                    spends[i] = { unlockingScript: txInput.unlockingScript?.toHex() ?? "" };
+                }
+            }
+            // Complete the action with our signatures
+            const signResult = await ctx.wallet.signAction({
+                reference: createResult.signableTransaction.reference,
+                spends,
+            });
+            if ("error" in signResult) {
+                return { error: String(signResult.error) };
+            }
+            return {
+                txid: signResult.txid,
+                beef: signResult.tx ? Array.from(signResult.tx) : undefined,
+            };
+        }
+        catch (error) {
+            return {
+                error: error instanceof Error ? error.message : "unknown-error",
+            };
+        }
+    },
+};
 // Export skills array for registry
-export const sweepSkills = [sweepBsv];
+export const sweepSkills = [sweepBsv, sweepOrdinals];

package/dist/api/sweep/types.d.ts

@@ -28,3 +28,26 @@ export interface SweepBsvResponse {
     /** Error message if failed */
     error?: string;
 }
+/** Input for ordinal sweep operations */
+export interface SweepOrdinalInput extends SweepInput {
+    /** Content type from ordfs metadata */
+    contentType?: string;
+    /** Origin outpoint for tracking */
+    origin?: string;
+}
+/** Request to sweep ordinals */
+export interface SweepOrdinalsRequest {
+    /** Ordinal UTXOs to sweep */
+    inputs: SweepOrdinalInput[];
+    /** WIF private key controlling the inputs */
+    wif: string;
+}
+/** Response from ordinal sweep operation */
+export interface SweepOrdinalsResponse {
+    /** Transaction ID if successful */
+    txid?: string;
+    /** BEEF (transaction with validity proof) */
+    beef?: number[];
+    /** Error message if failed */
+    error?: string;
+}

package/dist/api/tokens/index.js

@@ -289,7 +289,7 @@ export const sendBsv21 = {
                     inputDescription: "Token input",
                 })),
                 outputs,
-                options: { signAndProcess: false },
+                options: { signAndProcess: false, randomizeOutputs: false },
             });
             if ("error" in createResult && createResult.error) {
                 return { error: String(createResult.error) };
@@ -421,7 +421,7 @@ export const purchaseBsv21 = {
                     },
                 ],
                 outputs,
-                options: { signAndProcess: false },
+                options: { signAndProcess: false, randomizeOutputs: false },
             });
             if ("error" in createResult && createResult.error) {
                 return { error: String(createResult.error) };

package/dist/backup/FileBackupProvider.d.ts

@@ -0,0 +1,96 @@
+import { Zip, ZipDeflate } from "fflate";
+import type { sdk } from "@bsv/wallet-toolbox-mobile/out/src/index.client.js";
+import type { TableSettings } from "@bsv/wallet-toolbox-mobile/out/src/storage/schema/tables/TableSettings.js";
+import type { TableSyncState } from "@bsv/wallet-toolbox-mobile/out/src/storage/schema/tables/TableSyncState.js";
+import type { TableUser } from "@bsv/wallet-toolbox-mobile/out/src/storage/schema/tables/TableUser.js";
+type AuthId = sdk.AuthId;
+type ProcessSyncChunkResult = sdk.ProcessSyncChunkResult;
+type RequestSyncChunkArgs = sdk.RequestSyncChunkArgs;
+type SyncChunk = sdk.SyncChunk;
+type WalletStorageProvider = sdk.WalletStorageProvider;
+type WalletServices = sdk.WalletServices;
+/**
+ * FileBackupProvider implements WalletStorageProvider to receive sync chunks
+ * during wallet export. It encodes each chunk with MessagePack and streams
+ * it directly to a fflate Zip instance.
+ *
+ * Usage:
+ * 1. Create fflate.Zip with streaming callback
+ * 2. Create FileBackupProvider with the zip instance
+ * 3. Call storage.syncToWriter(auth, provider)
+ * 4. Provider receives processSyncChunk() calls and writes to zip
+ * 5. Call provider.getChunkCount() to get chunk count for manifest
+ *
+ * @example
+ * ```typescript
+ * import { Zip } from 'fflate';
+ *
+ * const chunks: Uint8Array[] = [];
+ * const zip = new Zip((err, data, final) => {
+ *   if (err) throw err;
+ *   chunks.push(data);
+ *   if (final) {
+ *     const blob = new Blob(chunks, { type: 'application/zip' });
+ *     // Download or save blob
+ *   }
+ * });
+ *
+ * const provider = new FileBackupProvider(zip, storage.getSettings(), identityKey);
+ * await storage.syncToWriter(auth, provider);
+ * console.log(`Exported ${provider.getChunkCount()} chunks`);
+ * ```
+ */
+export declare class FileBackupProvider implements WalletStorageProvider {
+    private zip;
+    private chunkCount;
+    private settings;
+    private identityKey;
+    constructor(zip: Zip, settings: TableSettings, identityKey: string);
+    /**
+     * Get the number of chunks written. Call after sync completes.
+     */
+    getChunkCount(): number;
+    /**
+     * Add a file to the zip archive with compression.
+     * Creates a ZipDeflate stream and pushes the data in one chunk.
+     */
+    private addFileToZip;
+    isStorageProvider(): boolean;
+    setServices(_v: WalletServices): void;
+    findOrInsertSyncStateAuth(_auth: AuthId, _storageIdentityKey: string, _storageName: string): Promise<{
+        syncState: TableSyncState;
+        isNew: boolean;
+    }>;
+    setActive(_auth: AuthId, _newActiveStorageIdentityKey: string): Promise<number>;
+    getSyncChunk(_args: RequestSyncChunkArgs): Promise<SyncChunk>;
+    /**
+     * Receives sync chunks from WalletStorageManager.syncToWriter().
+     * Encodes each chunk with MessagePack and adds to the zip.
+     */
+    processSyncChunk(_args: RequestSyncChunkArgs, chunk: SyncChunk): Promise<ProcessSyncChunkResult>;
+    makeAvailable(): Promise<TableSettings>;
+    migrate(_storageName: string, _storageIdentityKey: string): Promise<string>;
+    destroy(): Promise<void>;
+    findOrInsertUser(identityKey: string): Promise<{
+        user: TableUser;
+        isNew: boolean;
+    }>;
+    abortAction(_auth: AuthId, _args: unknown): Promise<never>;
+    createAction(_auth: AuthId, _args: unknown): Promise<never>;
+    processAction(_auth: AuthId, _args: unknown): Promise<never>;
+    internalizeAction(_auth: AuthId, _args: unknown): Promise<never>;
+    insertCertificateAuth(_auth: AuthId, _certificate: unknown): Promise<number>;
+    relinquishCertificate(_auth: AuthId, _args: unknown): Promise<number>;
+    relinquishOutput(_auth: AuthId, _args: unknown): Promise<number>;
+    isAvailable(): boolean;
+    getServices(): WalletServices;
+    getSettings(): TableSettings;
+    findCertificatesAuth(_auth: AuthId, _args: unknown): Promise<never[]>;
+    findOutputBasketsAuth(_auth: AuthId, _args: unknown): Promise<never[]>;
+    findOutputsAuth(_auth: AuthId, _args: unknown): Promise<never[]>;
+    findProvenTxReqs(_args: unknown): Promise<never[]>;
+    listActions(_auth: AuthId, _vargs: unknown): Promise<never>;
+    listCertificates(_auth: AuthId, _vargs: unknown): Promise<never>;
+    listOutputs(_auth: AuthId, _vargs: unknown): Promise<never>;
+}
+export { Zip, ZipDeflate };

package/dist/backup/FileBackupProvider.js

@@ -0,0 +1,184 @@
+import { encode } from "@msgpack/msgpack";
+import { Zip, ZipDeflate } from "fflate";
+/**
+ * FileBackupProvider implements WalletStorageProvider to receive sync chunks
+ * during wallet export. It encodes each chunk with MessagePack and streams
+ * it directly to a fflate Zip instance.
+ *
+ * Usage:
+ * 1. Create fflate.Zip with streaming callback
+ * 2. Create FileBackupProvider with the zip instance
+ * 3. Call storage.syncToWriter(auth, provider)
+ * 4. Provider receives processSyncChunk() calls and writes to zip
+ * 5. Call provider.getChunkCount() to get chunk count for manifest
+ *
+ * @example
+ * ```typescript
+ * import { Zip } from 'fflate';
+ *
+ * const chunks: Uint8Array[] = [];
+ * const zip = new Zip((err, data, final) => {
+ *   if (err) throw err;
+ *   chunks.push(data);
+ *   if (final) {
+ *     const blob = new Blob(chunks, { type: 'application/zip' });
+ *     // Download or save blob
+ *   }
+ * });
+ *
+ * const provider = new FileBackupProvider(zip, storage.getSettings(), identityKey);
+ * await storage.syncToWriter(auth, provider);
+ * console.log(`Exported ${provider.getChunkCount()} chunks`);
+ * ```
+ */
+export class FileBackupProvider {
+    zip;
+    chunkCount = 0;
+    settings;
+    identityKey;
+    constructor(zip, settings, identityKey) {
+        this.zip = zip;
+        this.settings = settings;
+        this.identityKey = identityKey;
+    }
+    /**
+     * Get the number of chunks written. Call after sync completes.
+     */
+    getChunkCount() {
+        return this.chunkCount;
+    }
+    /**
+     * Add a file to the zip archive with compression.
+     * Creates a ZipDeflate stream and pushes the data in one chunk.
+     */
+    addFileToZip(filename, data) {
+        const deflate = new ZipDeflate(filename, { level: 6 });
+        this.zip.add(deflate);
+        deflate.push(data, true); // true = final chunk
+    }
+    // WalletStorageProvider interface methods
+    isStorageProvider() {
+        return false;
+    }
+    setServices(_v) {
+        // Not needed for backup
+    }
+    // WalletStorageSync interface methods
+    async findOrInsertSyncStateAuth(_auth, _storageIdentityKey, _storageName) {
+        throw new Error("Not supported: findOrInsertSyncStateAuth");
+    }
+    async setActive(_auth, _newActiveStorageIdentityKey) {
+        throw new Error("Not supported: setActive");
+    }
+    async getSyncChunk(_args) {
+        throw new Error("Not supported: getSyncChunk - this is a write-only provider");
+    }
+    /**
+     * Receives sync chunks from WalletStorageManager.syncToWriter().
+     * Encodes each chunk with MessagePack and adds to the zip.
+     */
+    async processSyncChunk(_args, chunk) {
+        const chunkName = `chunk-${String(this.chunkCount).padStart(4, "0")}.bin`;
+        const encoded = encode(chunk);
+        // Add chunk to zip with compression using ZipDeflate
+        this.addFileToZip(chunkName, new Uint8Array(encoded));
+        this.chunkCount++;
+        // Check if this chunk has any data - if all arrays are empty or undefined, we're done
+        const hasData = (chunk.provenTxs && chunk.provenTxs.length > 0) ||
+            (chunk.provenTxReqs && chunk.provenTxReqs.length > 0) ||
+            (chunk.outputBaskets && chunk.outputBaskets.length > 0) ||
+            (chunk.txLabels && chunk.txLabels.length > 0) ||
+            (chunk.outputTags && chunk.outputTags.length > 0) ||
+            (chunk.transactions && chunk.transactions.length > 0) ||
+            (chunk.txLabelMaps && chunk.txLabelMaps.length > 0) ||
+            (chunk.commissions && chunk.commissions.length > 0) ||
+            (chunk.outputs && chunk.outputs.length > 0) ||
+            (chunk.outputTagMaps && chunk.outputTagMaps.length > 0) ||
+            (chunk.certificates && chunk.certificates.length > 0) ||
+            (chunk.certificateFields && chunk.certificateFields.length > 0);
+        return {
+            done: !hasData,
+            maxUpdated_at: undefined,
+            updates: 0,
+            inserts: 0,
+        };
+    }
+    // WalletStorageWriter interface methods (throw not supported)
+    async makeAvailable() {
+        return this.settings;
+    }
+    async migrate(_storageName, _storageIdentityKey) {
+        throw new Error("Not supported: migrate");
+    }
+    async destroy() {
+        throw new Error("Not supported: destroy");
+    }
+    async findOrInsertUser(identityKey) {
+        // Return a mock user for backup purposes
+        const now = new Date();
+        return {
+            user: {
+                userId: 1,
+                identityKey: identityKey || this.identityKey,
+                activeStorage: this.settings.storageIdentityKey || "",
+                created_at: now,
+                updated_at: now,
+            },
+            isNew: false,
+        };
+    }
+    async abortAction(_auth, _args) {
+        throw new Error("Not supported: abortAction");
+    }
+    async createAction(_auth, _args) {
+        throw new Error("Not supported: createAction");
+    }
+    async processAction(_auth, _args) {
+        throw new Error("Not supported: processAction");
+    }
+    async internalizeAction(_auth, _args) {
+        throw new Error("Not supported: internalizeAction");
+    }
+    async insertCertificateAuth(_auth, _certificate) {
+        throw new Error("Not supported: insertCertificateAuth");
+    }
+    async relinquishCertificate(_auth, _args) {
+        throw new Error("Not supported: relinquishCertificate");
+    }
+    async relinquishOutput(_auth, _args) {
+        throw new Error("Not supported: relinquishOutput");
+    }
+    // WalletStorageReader interface methods (throw not supported)
+    isAvailable() {
+        return true;
+    }
+    getServices() {
+        throw new Error("Not supported: getServices");
+    }
+    getSettings() {
+        return this.settings;
+    }
+    async findCertificatesAuth(_auth, _args) {
+        throw new Error("Not supported: findCertificatesAuth");
+    }
+    async findOutputBasketsAuth(_auth, _args) {
+        throw new Error("Not supported: findOutputBasketsAuth");
+    }
+    async findOutputsAuth(_auth, _args) {
+        throw new Error("Not supported: findOutputsAuth");
+    }
+    async findProvenTxReqs(_args) {
+        throw new Error("Not supported: findProvenTxReqs");
+    }
+    async listActions(_auth, _vargs) {
+        throw new Error("Not supported: listActions");
+    }
+    async listCertificates(_auth, _vargs) {
+        throw new Error("Not supported: listCertificates");
+    }
+    async listOutputs(_auth, _vargs) {
+        throw new Error("Not supported: listOutputs");
+    }
+}
+// Re-export Zip and ZipDeflate for convenience
+export { Zip, ZipDeflate };

package/dist/backup/FileRestoreReader.d.ts

@@ -0,0 +1,58 @@
+import type { Unzipped } from "fflate";
+import type { sdk } from "@bsv/wallet-toolbox-mobile/out/src/index.client.js";
+import type { TableSettings } from "@bsv/wallet-toolbox-mobile/out/src/storage/schema/tables/TableSettings.js";
+import type { BackupManifest } from "./types";
+type RequestSyncChunkArgs = sdk.RequestSyncChunkArgs;
+type SyncChunk = sdk.SyncChunk;
+type WalletStorageSyncReader = sdk.WalletStorageSyncReader;
+/**
+ * FileRestoreReader implements WalletStorageSyncReader to serve sync chunks
+ * from a previously exported backup ZIP file during wallet restore.
+ *
+ * Usage:
+ * 1. Unzip the backup file with fflate.unzip()
+ * 2. Read and parse manifest.json
+ * 3. Create FileRestoreReader with unzipped data and manifest
+ * 4. Call storage.syncFromReader(identityKey, reader)
+ * 5. Reader serves chunks sequentially via getSyncChunk()
+ *
+ * @example
+ * ```typescript
+ * import { unzip } from 'fflate';
+ *
+ * const zipData = new Uint8Array(await file.arrayBuffer());
+ * const unzipped = await new Promise<Unzipped>((resolve, reject) => {
+ *   unzip(zipData, (err, data) => err ? reject(err) : resolve(data));
+ * });
+ *
+ * const manifest = JSON.parse(
+ *   new TextDecoder().decode(unzipped['manifest.json'])
+ * );
+ *
+ * const reader = new FileRestoreReader(unzipped, manifest);
+ * await storage.syncFromReader(manifest.identityKey, reader);
+ * ```
+ */
+export declare class FileRestoreReader implements WalletStorageSyncReader {
+    private unzipped;
+    private manifest;
+    private currentChunkIndex;
+    private settings;
+    constructor(unzipped: Unzipped, manifest: BackupManifest);
+    /**
+     * Get the backup manifest.
+     */
+    getManifest(): BackupManifest;
+    /**
+     * Reset the reader to start from the beginning.
+     * Call this if you need to re-read the backup.
+     */
+    reset(): void;
+    makeAvailable(): Promise<TableSettings>;
+    /**
+     * Returns sync chunks sequentially from the backup.
+     * When all chunks are consumed, returns an empty chunk to signal completion.
+     */
+    getSyncChunk(args: RequestSyncChunkArgs): Promise<SyncChunk>;
+}
+export {};

package/dist/backup/FileRestoreReader.js

@@ -0,0 +1,88 @@
+import { decode } from "@msgpack/msgpack";
+/**
+ * FileRestoreReader implements WalletStorageSyncReader to serve sync chunks
+ * from a previously exported backup ZIP file during wallet restore.
+ *
+ * Usage:
+ * 1. Unzip the backup file with fflate.unzip()
+ * 2. Read and parse manifest.json
+ * 3. Create FileRestoreReader with unzipped data and manifest
+ * 4. Call storage.syncFromReader(identityKey, reader)
+ * 5. Reader serves chunks sequentially via getSyncChunk()
+ *
+ * @example
+ * ```typescript
+ * import { unzip } from 'fflate';
+ *
+ * const zipData = new Uint8Array(await file.arrayBuffer());
+ * const unzipped = await new Promise<Unzipped>((resolve, reject) => {
+ *   unzip(zipData, (err, data) => err ? reject(err) : resolve(data));
+ * });
+ *
+ * const manifest = JSON.parse(
+ *   new TextDecoder().decode(unzipped['manifest.json'])
+ * );
+ *
+ * const reader = new FileRestoreReader(unzipped, manifest);
+ * await storage.syncFromReader(manifest.identityKey, reader);
+ * ```
+ */
+export class FileRestoreReader {
+    unzipped;
+    manifest;
+    currentChunkIndex = 0;
+    settings;
+    constructor(unzipped, manifest) {
+        this.unzipped = unzipped;
+        this.manifest = manifest;
+        // Create settings from manifest
+        this.settings = {
+            created_at: new Date(manifest.createdAt),
+            updated_at: new Date(manifest.createdAt),
+            storageIdentityKey: `backup-${manifest.identityKey.slice(0, 16)}`,
+            storageName: "FileBackup",
+            chain: manifest.chain,
+            dbtype: "IndexedDB",
+            maxOutputScript: 256,
+        };
+    }
+    /**
+     * Get the backup manifest.
+     */
+    getManifest() {
+        return this.manifest;
+    }
+    /**
+     * Reset the reader to start from the beginning.
+     * Call this if you need to re-read the backup.
+     */
+    reset() {
+        this.currentChunkIndex = 0;
+    }
+    // WalletStorageSyncReader interface methods
+    async makeAvailable() {
+        return this.settings;
+    }
+    /**
+     * Returns sync chunks sequentially from the backup.
+     * When all chunks are consumed, returns an empty chunk to signal completion.
+     */
+    async getSyncChunk(args) {
+        if (this.currentChunkIndex >= this.manifest.chunkCount) {
+            // Return empty chunk to signal completion
+            return {
+                fromStorageIdentityKey: this.settings.storageIdentityKey,
+                toStorageIdentityKey: args.toStorageIdentityKey,
+                userIdentityKey: this.manifest.identityKey,
+            };
+        }
+        const chunkName = `chunk-${String(this.currentChunkIndex).padStart(4, "0")}.bin`;
+        const chunkData = this.unzipped[chunkName];
+        if (!chunkData) {
+            throw new Error(`Missing chunk file: ${chunkName}`);
+        }
+        const chunk = decode(chunkData);
+        this.currentChunkIndex++;
+        return chunk;
+    }
+}

package/dist/backup/index.d.ts

@@ -0,0 +1,5 @@
+export { FileBackupProvider, Zip, ZipDeflate } from "./FileBackupProvider";
+export { FileRestoreReader } from "./FileRestoreReader";
+export type { BackupManifest, BackupProgressEvent, BackupProgressCallback, } from "./types";
+export { unzip } from "fflate";
+export type { Unzipped } from "fflate";

package/dist/backup/index.js

@@ -0,0 +1,4 @@
+export { FileBackupProvider, Zip, ZipDeflate } from "./FileBackupProvider";
+export { FileRestoreReader } from "./FileRestoreReader";
+// Re-export fflate utilities needed for restore
+export { unzip } from "fflate";

package/dist/backup/types.d.ts

@@ -0,0 +1,31 @@
+import type { sdk } from "@bsv/wallet-toolbox-mobile/out/src/index.client.js";
+type Chain = sdk.Chain;
+/**
+ * Manifest stored in the backup ZIP file describing the backup contents.
+ */
+export interface BackupManifest {
+    /** Backup format version */
+    version: 1;
+    /** ISO timestamp when backup was created */
+    createdAt: string;
+    /** Network chain (main or test) */
+    chain: Chain;
+    /** Wallet identity public key */
+    identityKey: string;
+    /** Number of sync chunks in the backup */
+    chunkCount: number;
+}
+/**
+ * Progress events emitted during backup/restore operations.
+ */
+export interface BackupProgressEvent {
+    stage: "preparing" | "exporting" | "downloading" | "uploading" | "importing" | "complete";
+    message: string;
+    /** Optional progress percentage (0-100) */
+    progress?: number;
+}
+/**
+ * Callback type for progress updates during backup/restore.
+ */
+export type BackupProgressCallback = (event: BackupProgressEvent) => void;
+export {};

package/dist/backup/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export * from "./indexers";
 export * from "./sync";
 export * from "./cwi";
 export * from "./wallet";
+export * from "./backup";

package/dist/index.js

@@ -17,3 +17,5 @@ export * from "./sync";
 export * from "./cwi";
 // Wallet factory for creating 1Sat web wallets
 export * from "./wallet";
+// Backup providers for file-based wallet backup/restore
+export * from "./backup";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1sat/wallet-toolbox",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "BSV wallet library extending @bsv/wallet-toolbox with 1Sat Ordinals protocol support",
   "author": "1Sat Team",
   "license": "MIT",
@@ -39,7 +39,9 @@
   "dependencies": {
     "@bopen-io/templates": "^1.1.6",
     "@bsv/sdk": "^1.10.1",
-    "buffer": "^6.0.3"
+    "@msgpack/msgpack": "^3.1.3",
+    "buffer": "^6.0.3",
+    "fflate": "^0.8.2"
   },
   "peerDependencies": {
     "@bsv/wallet-toolbox-mobile": "npm:@bopen-io/wallet-toolbox-mobile@^1.7.20-idb-fix.15"