@arkade-os/sdk 0.3.13 → 0.4.0-next.1

package/dist/cjs/repositories/realm/schemas.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Realm object schemas for the Ark wallet.
+ *
+ * All schema names are prefixed with "Ark" to avoid collisions with
+ * other Realm schemas in the consuming application.
+ *
+ * Since `realm` is a peer dependency (not installed in this package),
+ * schemas are defined as plain JS objects conforming to Realm's
+ * ObjectSchema shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArkRealmSchemas = exports.ArkContractSchema = exports.ArkWalletStateSchema = exports.ArkTransactionSchema = exports.ArkUtxoSchema = exports.ArkVtxoSchema = void 0;
+exports.ArkVtxoSchema = {
+    name: "ArkVtxo",
+    primaryKey: "pk",
+    properties: {
+        pk: "string", // composite: `${txid}:${vout}`
+        address: { type: "string", indexed: true },
+        txid: "string",
+        vout: "int",
+        value: "int",
+        tapTree: "string", // hex-encoded
+        forfeitCb: "string",
+        forfeitS: "string",
+        intentCb: "string",
+        intentS: "string",
+        extraWitnessJson: "string?",
+        statusJson: "string",
+        virtualStatusJson: "string",
+        spentBy: "string?",
+        settledBy: "string?",
+        arkTxId: "string?",
+        createdAt: "string", // ISO 8601
+        isUnrolled: "bool",
+        isSpent: "bool?",
+        assetsJson: "string?",
+    },
+};
+exports.ArkUtxoSchema = {
+    name: "ArkUtxo",
+    primaryKey: "pk",
+    properties: {
+        pk: "string", // composite: `${txid}:${vout}`
+        address: { type: "string", indexed: true },
+        txid: "string",
+        vout: "int",
+        value: "int",
+        tapTree: "string", // hex-encoded
+        forfeitCb: "string",
+        forfeitS: "string",
+        intentCb: "string",
+        intentS: "string",
+        extraWitnessJson: "string?",
+        statusJson: "string",
+    },
+};
+exports.ArkTransactionSchema = {
+    name: "ArkTransaction",
+    primaryKey: "pk",
+    properties: {
+        pk: "string", // composite: `${address}:${boardingTxid}:${commitmentTxid}:${arkTxid}`
+        address: { type: "string", indexed: true },
+        boardingTxid: "string",
+        commitmentTxid: "string",
+        arkTxid: "string",
+        type: "string",
+        amount: "int",
+        settled: "bool",
+        createdAt: "int",
+        assetsJson: "string?",
+    },
+};
+exports.ArkWalletStateSchema = {
+    name: "ArkWalletState",
+    primaryKey: "key",
+    properties: {
+        key: "string",
+        lastSyncTime: "int?",
+        settingsJson: "string?",
+    },
+};
+exports.ArkContractSchema = {
+    name: "ArkContract",
+    primaryKey: "script",
+    properties: {
+        script: "string",
+        address: "string",
+        type: { type: "string", indexed: true },
+        state: { type: "string", indexed: true },
+        paramsJson: "string",
+        createdAt: "int",
+        expiresAt: "int?",
+        label: "string?",
+        metadataJson: "string?",
+    },
+};
+/**
+ * All Realm schemas needed by the Ark wallet repositories.
+ * Pass this array to your Realm configuration's `schema` property.
+ */
+exports.ArkRealmSchemas = [
+    exports.ArkVtxoSchema,
+    exports.ArkUtxoSchema,
+    exports.ArkTransactionSchema,
+    exports.ArkWalletStateSchema,
+    exports.ArkContractSchema,
+];

package/dist/cjs/repositories/realm/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Minimal interface for the subset of the Realm API used by the
+ * Ark repositories.  Consumers pass their real Realm instance and
+ * the compiler validates it satisfies this shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/repositories/realm/walletRepository.js

@@ -0,0 +1,273 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealmWalletRepository = void 0;
+const serialization_1 = require("../serialization");
+/**
+ * Realm-based implementation of WalletRepository.
+ *
+ * Consumers must open Realm with the schemas from `./schemas.ts` and pass
+ * the instance to the constructor.
+ *
+ * Realm handles schema creation on open, so `ensureInit()` is a no-op.
+ * The consumer owns the Realm lifecycle — `[Symbol.asyncDispose]` is a no-op.
+ */
+class RealmWalletRepository {
+    constructor(realm) {
+        this.realm = realm;
+        this.version = 1;
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────
+    async ensureInit() {
+        // Realm handles schema on open — nothing to initialise.
+    }
+    async [Symbol.asyncDispose]() {
+        // no-op — consumer owns the Realm lifecycle
+    }
+    // ── Clear ──────────────────────────────────────────────────────────
+    async clear() {
+        await this.ensureInit();
+        this.realm.write(() => {
+            this.realm.delete(this.realm.objects("ArkVtxo"));
+            this.realm.delete(this.realm.objects("ArkUtxo"));
+            this.realm.delete(this.realm.objects("ArkTransaction"));
+            this.realm.delete(this.realm.objects("ArkWalletState"));
+        });
+    }
+    // ── VTXO management ────────────────────────────────────────────────
+    async getVtxos(address) {
+        await this.ensureInit();
+        const results = this.realm
+            .objects("ArkVtxo")
+            .filtered("address == $0", address);
+        return [...results].map(vtxoObjectToDomain);
+    }
+    async saveVtxos(address, vtxos) {
+        await this.ensureInit();
+        this.realm.write(() => {
+            for (const vtxo of vtxos) {
+                const s = (0, serialization_1.serializeVtxo)(vtxo);
+                this.realm.create("ArkVtxo", {
+                    pk: `${s.txid}:${s.vout}`,
+                    address,
+                    txid: s.txid,
+                    vout: s.vout,
+                    value: s.value,
+                    tapTree: s.tapTree,
+                    forfeitCb: s.forfeitTapLeafScript.cb,
+                    forfeitS: s.forfeitTapLeafScript.s,
+                    intentCb: s.intentTapLeafScript.cb,
+                    intentS: s.intentTapLeafScript.s,
+                    statusJson: JSON.stringify(s.status),
+                    virtualStatusJson: JSON.stringify(s.virtualStatus),
+                    createdAt: typeof s.createdAt === "string"
+                        ? s.createdAt
+                        : s.createdAt instanceof Date
+                            ? s.createdAt.toISOString()
+                            : new Date(s.createdAt).toISOString(),
+                    isUnrolled: s.isUnrolled ?? false,
+                    isSpent: s.isSpent === undefined ? null : s.isSpent,
+                    spentBy: s.spentBy ?? null,
+                    settledBy: s.settledBy ?? null,
+                    arkTxId: s.arkTxId ?? null,
+                    extraWitnessJson: s.extraWitness
+                        ? JSON.stringify(s.extraWitness)
+                        : null,
+                    assetsJson: s.assets ? JSON.stringify(s.assets) : null,
+                }, "modified");
+            }
+        });
+    }
+    async deleteVtxos(address) {
+        await this.ensureInit();
+        this.realm.write(() => {
+            const toDelete = this.realm
+                .objects("ArkVtxo")
+                .filtered("address == $0", address);
+            this.realm.delete(toDelete);
+        });
+    }
+    // ── UTXO management ────────────────────────────────────────────────
+    async getUtxos(address) {
+        await this.ensureInit();
+        const results = this.realm
+            .objects("ArkUtxo")
+            .filtered("address == $0", address);
+        return [...results].map(utxoObjectToDomain);
+    }
+    async saveUtxos(address, utxos) {
+        await this.ensureInit();
+        this.realm.write(() => {
+            for (const utxo of utxos) {
+                const s = (0, serialization_1.serializeUtxo)(utxo);
+                this.realm.create("ArkUtxo", {
+                    pk: `${s.txid}:${s.vout}`,
+                    address,
+                    txid: s.txid,
+                    vout: s.vout,
+                    value: s.value,
+                    tapTree: s.tapTree,
+                    forfeitCb: s.forfeitTapLeafScript.cb,
+                    forfeitS: s.forfeitTapLeafScript.s,
+                    intentCb: s.intentTapLeafScript.cb,
+                    intentS: s.intentTapLeafScript.s,
+                    statusJson: JSON.stringify(s.status),
+                    extraWitnessJson: s.extraWitness
+                        ? JSON.stringify(s.extraWitness)
+                        : null,
+                }, "modified");
+            }
+        });
+    }
+    async deleteUtxos(address) {
+        await this.ensureInit();
+        this.realm.write(() => {
+            const toDelete = this.realm
+                .objects("ArkUtxo")
+                .filtered("address == $0", address);
+            this.realm.delete(toDelete);
+        });
+    }
+    // ── Transaction history ────────────────────────────────────────────
+    async getTransactionHistory(address) {
+        await this.ensureInit();
+        const results = this.realm
+            .objects("ArkTransaction")
+            .filtered("address == $0", address);
+        const txs = [...results].map(txObjectToDomain);
+        txs.sort((a, b) => a.createdAt - b.createdAt);
+        return txs;
+    }
+    async saveTransactions(address, txs) {
+        await this.ensureInit();
+        this.realm.write(() => {
+            for (const tx of txs) {
+                this.realm.create("ArkTransaction", {
+                    pk: `${address}:${tx.key.boardingTxid}:${tx.key.commitmentTxid}:${tx.key.arkTxid}`,
+                    address,
+                    boardingTxid: tx.key.boardingTxid,
+                    commitmentTxid: tx.key.commitmentTxid,
+                    arkTxid: tx.key.arkTxid,
+                    type: tx.type,
+                    amount: tx.amount,
+                    settled: tx.settled,
+                    createdAt: tx.createdAt,
+                    assetsJson: tx.assets
+                        ? JSON.stringify(tx.assets)
+                        : null,
+                }, "modified");
+            }
+        });
+    }
+    async deleteTransactions(address) {
+        await this.ensureInit();
+        this.realm.write(() => {
+            const toDelete = this.realm
+                .objects("ArkTransaction")
+                .filtered("address == $0", address);
+            this.realm.delete(toDelete);
+        });
+    }
+    // ── Wallet state ───────────────────────────────────────────────────
+    async getWalletState() {
+        await this.ensureInit();
+        const results = this.realm
+            .objects("ArkWalletState")
+            .filtered("key == $0", "state");
+        const items = [...results];
+        if (items.length === 0)
+            return null;
+        const obj = items[0];
+        const state = {};
+        if (obj.lastSyncTime !== null && obj.lastSyncTime !== undefined) {
+            state.lastSyncTime = obj.lastSyncTime;
+        }
+        if (obj.settingsJson) {
+            state.settings = JSON.parse(obj.settingsJson);
+        }
+        return state;
+    }
+    async saveWalletState(state) {
+        await this.ensureInit();
+        this.realm.write(() => {
+            this.realm.create("ArkWalletState", {
+                key: "state",
+                lastSyncTime: state.lastSyncTime ?? null,
+                settingsJson: state.settings
+                    ? JSON.stringify(state.settings)
+                    : null,
+            }, "modified");
+        });
+    }
+}
+exports.RealmWalletRepository = RealmWalletRepository;
+// ── Realm object → Domain converters ─────────────────────────────────────
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function vtxoObjectToDomain(obj) {
+    const serialized = {
+        txid: obj.txid,
+        vout: obj.vout,
+        value: obj.value,
+        tapTree: obj.tapTree,
+        forfeitTapLeafScript: {
+            cb: obj.forfeitCb,
+            s: obj.forfeitS,
+        },
+        intentTapLeafScript: {
+            cb: obj.intentCb,
+            s: obj.intentS,
+        },
+        status: JSON.parse(obj.statusJson),
+        virtualStatus: JSON.parse(obj.virtualStatusJson),
+        createdAt: new Date(obj.createdAt),
+        isUnrolled: obj.isUnrolled,
+        isSpent: obj.isSpent === null ? undefined : obj.isSpent,
+        spentBy: obj.spentBy ?? undefined,
+        settledBy: obj.settledBy ?? undefined,
+        arkTxId: obj.arkTxId ?? undefined,
+        extraWitness: obj.extraWitnessJson
+            ? JSON.parse(obj.extraWitnessJson)
+            : undefined,
+        assets: obj.assetsJson ? JSON.parse(obj.assetsJson) : undefined,
+    };
+    return (0, serialization_1.deserializeVtxo)(serialized);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function utxoObjectToDomain(obj) {
+    const serialized = {
+        txid: obj.txid,
+        vout: obj.vout,
+        value: obj.value,
+        tapTree: obj.tapTree,
+        forfeitTapLeafScript: {
+            cb: obj.forfeitCb,
+            s: obj.forfeitS,
+        },
+        intentTapLeafScript: {
+            cb: obj.intentCb,
+            s: obj.intentS,
+        },
+        status: JSON.parse(obj.statusJson),
+        extraWitness: obj.extraWitnessJson
+            ? JSON.parse(obj.extraWitnessJson)
+            : undefined,
+    };
+    return (0, serialization_1.deserializeUtxo)(serialized);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function txObjectToDomain(obj) {
+    const tx = {
+        key: {
+            boardingTxid: obj.boardingTxid,
+            commitmentTxid: obj.commitmentTxid,
+            arkTxid: obj.arkTxid,
+        },
+        type: obj.type,
+        amount: obj.amount,
+        settled: obj.settled,
+        createdAt: obj.createdAt,
+    };
+    if (obj.assetsJson) {
+        tx.assets = JSON.parse(obj.assetsJson);
+    }
+    return tx;
+}

package/dist/cjs/repositories/serialization.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deserializeUtxo = exports.deserializeVtxo = exports.deserializeTapLeaf = exports.serializeUtxo = exports.serializeVtxo = exports.serializeTapLeaf = void 0;
+const base_1 = require("@scure/base");
+const btc_signer_1 = require("@scure/btc-signer");
+const serializeTapLeaf = ([cb, s,]) => ({
+    cb: base_1.hex.encode(btc_signer_1.TaprootControlBlock.encode(cb)),
+    s: base_1.hex.encode(s),
+});
+exports.serializeTapLeaf = serializeTapLeaf;
+const serializeVtxo = (v) => ({
+    ...v,
+    tapTree: base_1.hex.encode(v.tapTree),
+    forfeitTapLeafScript: (0, exports.serializeTapLeaf)(v.forfeitTapLeafScript),
+    intentTapLeafScript: (0, exports.serializeTapLeaf)(v.intentTapLeafScript),
+    extraWitness: v.extraWitness?.map(base_1.hex.encode),
+});
+exports.serializeVtxo = serializeVtxo;
+const serializeUtxo = (u) => ({
+    ...u,
+    tapTree: base_1.hex.encode(u.tapTree),
+    forfeitTapLeafScript: (0, exports.serializeTapLeaf)(u.forfeitTapLeafScript),
+    intentTapLeafScript: (0, exports.serializeTapLeaf)(u.intentTapLeafScript),
+    extraWitness: u.extraWitness?.map(base_1.hex.encode),
+});
+exports.serializeUtxo = serializeUtxo;
+const deserializeTapLeaf = (t) => {
+    const cb = btc_signer_1.TaprootControlBlock.decode(base_1.hex.decode(t.cb));
+    const s = base_1.hex.decode(t.s);
+    return [cb, s];
+};
+exports.deserializeTapLeaf = deserializeTapLeaf;
+const deserializeVtxo = (o) => ({
+    ...o,
+    createdAt: new Date(o.createdAt),
+    tapTree: base_1.hex.decode(o.tapTree),
+    forfeitTapLeafScript: (0, exports.deserializeTapLeaf)(o.forfeitTapLeafScript),
+    intentTapLeafScript: (0, exports.deserializeTapLeaf)(o.intentTapLeafScript),
+    extraWitness: o.extraWitness?.map(base_1.hex.decode),
+});
+exports.deserializeVtxo = deserializeVtxo;
+const deserializeUtxo = (o) => ({
+    ...o,
+    tapTree: base_1.hex.decode(o.tapTree),
+    forfeitTapLeafScript: (0, exports.deserializeTapLeaf)(o.forfeitTapLeafScript),
+    intentTapLeafScript: (0, exports.deserializeTapLeaf)(o.intentTapLeafScript),
+    extraWitness: o.extraWitness?.map(base_1.hex.decode),
+});
+exports.deserializeUtxo = deserializeUtxo;

package/dist/cjs/repositories/sqlite/contractRepository.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLiteContractRepository = void 0;
+/**
+ * SQLite-based implementation of ContractRepository.
+ *
+ * Uses the SQLExecutor interface so consumers can plug in any SQLite driver
+ * (expo-sqlite, better-sqlite3, etc.).
+ *
+ * Tables are created lazily on first operation via `ensureInit()`.
+ * The consumer owns the SQLExecutor lifecycle — `[Symbol.asyncDispose]` is a no-op.
+ */
+class SQLiteContractRepository {
+    constructor(db, options) {
+        this.db = db;
+        this.version = 1;
+        this.initPromise = null;
+        this.prefix = sanitizePrefix(options?.prefix ?? "ark_");
+        this.table = `${this.prefix}contracts`;
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────
+    ensureInit() {
+        if (!this.initPromise) {
+            this.initPromise = this.init();
+        }
+        return this.initPromise;
+    }
+    async init() {
+        await this.db.run(`
+            CREATE TABLE IF NOT EXISTS ${this.table} (
+                script TEXT PRIMARY KEY,
+                address TEXT NOT NULL,
+                type TEXT NOT NULL,
+                state TEXT NOT NULL,
+                params_json TEXT NOT NULL,
+                created_at INTEGER NOT NULL,
+                expires_at INTEGER,
+                label TEXT,
+                metadata_json TEXT
+            )
+        `);
+        await this.db.run(`CREATE INDEX IF NOT EXISTS idx_${this.prefix}contracts_type ON ${this.table} (type)`);
+        await this.db.run(`CREATE INDEX IF NOT EXISTS idx_${this.prefix}contracts_state ON ${this.table} (state)`);
+    }
+    async [Symbol.asyncDispose]() {
+        // no-op — consumer owns the SQLExecutor lifecycle
+    }
+    // ── Clear ──────────────────────────────────────────────────────────
+    async clear() {
+        await this.ensureInit();
+        await this.db.run(`DELETE FROM ${this.table}`);
+    }
+    // ── Contract management ────────────────────────────────────────────
+    async getContracts(filter) {
+        await this.ensureInit();
+        const conditions = [];
+        const params = [];
+        if (filter) {
+            this.addFilterCondition(conditions, params, "script", filter.script);
+            this.addFilterCondition(conditions, params, "state", filter.state);
+            this.addFilterCondition(conditions, params, "type", filter.type);
+        }
+        let sql = `SELECT * FROM ${this.table}`;
+        if (conditions.length > 0) {
+            sql += ` WHERE ${conditions.join(" AND ")}`;
+        }
+        const rows = await this.db.all(sql, params);
+        return rows.map(contractRowToDomain);
+    }
+    async saveContract(contract) {
+        await this.ensureInit();
+        await this.db.run(`INSERT OR REPLACE INTO ${this.table}
+                (script, address, type, state, params_json,
+                 created_at, expires_at, label, metadata_json)
+             VALUES (?, ?, ?, ?, ?,
+                     ?, ?, ?, ?)`, [
+            contract.script,
+            contract.address,
+            contract.type,
+            contract.state,
+            JSON.stringify(contract.params),
+            contract.createdAt,
+            contract.expiresAt ?? null,
+            contract.label ?? null,
+            contract.metadata ? JSON.stringify(contract.metadata) : null,
+        ]);
+    }
+    async deleteContract(script) {
+        await this.ensureInit();
+        await this.db.run(`DELETE FROM ${this.table} WHERE script = ?`, [
+            script,
+        ]);
+    }
+    // ── Helpers ─────────────────────────────────────────────────────────
+    addFilterCondition(conditions, params, column, value) {
+        if (value === undefined)
+            return;
+        if (Array.isArray(value)) {
+            if (value.length === 0)
+                return;
+            const placeholders = value.map(() => "?").join(", ");
+            conditions.push(`${column} IN (${placeholders})`);
+            params.push(...value);
+        }
+        else {
+            conditions.push(`${column} = ?`);
+            params.push(value);
+        }
+    }
+}
+exports.SQLiteContractRepository = SQLiteContractRepository;
+// ── Row → Domain converter ──────────────────────────────────────────────
+const SAFE_PREFIX = /^[a-zA-Z0-9_]+$/;
+function sanitizePrefix(prefix) {
+    if (!SAFE_PREFIX.test(prefix)) {
+        throw new Error(`Invalid table prefix "${prefix}": only letters, digits, and underscores are allowed`);
+    }
+    return prefix;
+}
+function contractRowToDomain(row) {
+    const contract = {
+        script: row.script,
+        address: row.address,
+        type: row.type,
+        state: row.state,
+        params: JSON.parse(row.params_json),
+        createdAt: row.created_at,
+    };
+    if (row.expires_at !== null) {
+        contract.expiresAt = row.expires_at;
+    }
+    if (row.label !== null) {
+        contract.label = row.label;
+    }
+    if (row.metadata_json !== null) {
+        contract.metadata = JSON.parse(row.metadata_json);
+    }
+    return contract;
+}

package/dist/cjs/repositories/sqlite/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLiteContractRepository = exports.SQLiteWalletRepository = void 0;
+var walletRepository_1 = require("./walletRepository");
+Object.defineProperty(exports, "SQLiteWalletRepository", { enumerable: true, get: function () { return walletRepository_1.SQLiteWalletRepository; } });
+var contractRepository_1 = require("./contractRepository");
+Object.defineProperty(exports, "SQLiteContractRepository", { enumerable: true, get: function () { return contractRepository_1.SQLiteContractRepository; } });

package/dist/cjs/repositories/sqlite/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });