@chironbuilder/ootle-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chironbuilds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @chironbuilder/ootle-sdk
+
+A shared TypeScript client for [Tari Ootle](https://github.com/tari-project/tari-ootle) (L2): account
+derivation, balances, transaction building/submission with automatic input resolution, HTLCs, and
+stealth/confidential transfers.
+
+This is the account core extracted from two independently-built wallets that had converged on
+(mostly) the same code by hand — [Sapient](https://github.com/chironbuilds/tari-wallet), a Chrome
+extension, and the [Tari L1 web wallet](https://universe.tari.mw)'s Ootle L2 support — after each had
+picked up its own fixes the other was missing. This package exists so that stops happening: one
+wallet core, used by both, with platform-specific concerns (storage, in this case) injected rather
+than hardcoded.
+
+**Status: early.** Extracted and reconciled in one pass; not yet wired back into either of the two
+wallets above (they still carry their own local copies for now). Treat `0.x` as exactly that.
+
+## Install
+
+```bash
+npm install @chironbuilder/ootle-sdk
+```
+
+This package vendors two small, still-unmerged patches: `@tari-project/ootle` (a `covenant_claims`
+serialization gap in `StealthTransferStatement.toCompactJson()`, harmless for every transfer this SDK
+builds today but not yet upstream-fixed) and `@tari-project/ootle-wasm` (adds
+`createConfidentialWithdrawProofLiteral`, needed for confidential-vault withdrawals and not in the
+published `0.39.x` builds). See `vendor/*/README.md` for each. Both are tracked for removal once
+upstream ships the real fix — check there before assuming either is still needed.
+
+## Storage
+
+The SDK never touches a concrete storage API directly. It reads and writes through a small
+`KeyValueStore` interface — configure one adapter, once, before calling anything else:
+
+```ts
+import { configureOotleStorage } from "@chironbuilder/ootle-sdk";
+import { chromeStorageAdapter } from "@chironbuilder/ootle-sdk/adapters";
+// or: localStorageAdapter, inMemoryAdapter (tests)
+
+configureOotleStorage(chromeStorageAdapter());
+```
+
+Write your own adapter for any other host — it's three methods (`get`/`set`/`remove`).
+
+This only covers what the account core itself needs (shielded outputs, pending shields, the
+private-payment scan cursor, the known-substate-versions cache). Address books, connected-site
+permissions, daemon connections, and a full transaction-history UI are application concerns with
+very different shapes per host — keep those in your own app's storage layer.
+
+## Usage
+
+```ts
+import { OotleAccount, toOotleNetwork } from "@chironbuilder/ootle-sdk";
+
+const account = OotleAccount.fromSeed(entropy, /* index */ 0, "esmeralda");
+
+const balances = await account.getBalances();
+await account.send(recipientWalletAddress, resourceAddress, amount);
+```
+
+See `src/wallet.ts`'s doc comments for the full `OotleAccount` surface — `send`, `sendPrivately`,
+`shield`/`unshield`, `htlcFund`/`htlcClaim`/`htlcRefund`, `claimTestnetXtr`, `execute` (the general
+instruction-builder escape hatch, with automatic missing-input discovery and lock-contention retry).
+
+## What's in here, and what isn't
+
+- **Account core** (`wallet.ts`): `OotleAccount`, balance/plan-resolution helpers, the transaction
+  auto-resolve retry loop.
+- **Crypto/derivation**: `derivation.ts`, `domainHash.ts`, `componentAddress.ts`, `vault.ts`,
+  `ownershipProof.ts`, `confidential.ts`.
+- **HTLC**: `htlc.ts`.
+- **Storage abstraction**: `storage.ts` + `adapters.ts`.
+- **Not included**: UI, an approval/permission model for dApp connections, address books, daemon
+  (`tari_ootle_walletd`) relay support, transaction-history persistence. Those stay in each
+  consuming application.
+
+## Developing
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). (The two wallets this was extracted from are licensed separately,
+under PolyForm Noncommercial; this SDK is deliberately more permissive so other Ootle projects can
+build on it without that restriction.)

package/dist/accountApi.d.ts

@@ -0,0 +1,33 @@
+import type { IndexerProvider } from "@tari-project/ootle-indexer";
+import type { Instruction, SubstateRequirement } from "@tari-project/ootle-ts-bindings";
+import type { TokenBalance } from "./wallet";
+export interface TransactionExecuteOpts {
+    maxFee?: bigint;
+    dryRun?: boolean;
+    inputs?: SubstateRequirement[];
+    maxRetries?: number;
+}
+/**
+ * Shared surface both `OotleAccount` (this extension's own seed-derived signer) and `DaemonAccount`
+ * (a relayed account on a connected `tari_ootle_walletd`) implement — the "hardware wallet" split:
+ * everywhere in background/index.ts that touches "the active account" is written against this
+ * interface, so it doesn't need to know or care which kind of account is actually active.
+ */
+export interface WalletAccountApi {
+    getComponentAddress(): Promise<string>;
+    getWalletAddress(): Promise<string>;
+    getBalances(): Promise<TokenBalance[]>;
+    /** The indexer connection this account's reads are served from — used for general-purpose
+     * substate lookups (`tari_getSubstate`) that aren't tied to any one account method. */
+    getProvider(): Promise<IndexerProvider>;
+    execute(instructions: Instruction[], opts?: TransactionExecuteOpts): Promise<unknown>;
+    /** `recipientAddress` accepts either the recipient's bech32m "otl_..." wallet address or their
+     * on-chain `component_...` address — both identify the same account, but only the former lets
+     * an implementation create the recipient's account on the fly if it doesn't exist yet (that
+     * requires the owner public key the wallet address encodes; a bare component address never
+     * reveals it, so that form can only pay an account that already exists). Prefer asking senders
+     * for the wallet address — it's the one form that always works. */
+    send(recipientAddress: string, resourceAddress: string, amount: bigint, maxFee?: bigint): Promise<unknown>;
+    claimTestnetXtr(): Promise<unknown>;
+}
+//# sourceMappingURL=accountApi.d.ts.map

package/dist/accountApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountApi.d.ts","sourceRoot":"","sources":["../src/accountApi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACvC;2FACuF;IACvF,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACxC,OAAO,CAAC,YAAY,EAAE,WAAW,EAAE,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF;;;;;uEAKmE;IACnE,IAAI,CAAC,gBAAgB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3G,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC"}

package/dist/accountApi.js

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

package/dist/adapters.d.ts

@@ -0,0 +1,13 @@
+import type { KeyValueStore } from "./storage";
+/** For a Chrome (or any Manifest V3) extension. `chrome.storage.local` already stores structured
+ * values natively, so this is a thin wrapper, not a serializer. */
+export declare function chromeStorageAdapter(area?: chrome.storage.StorageArea): KeyValueStore;
+/** For a plain web page. `localStorage` only stores strings, so this serializes to/from JSON;
+ * unavailable or over quota (private browsing, storage disabled) degrades to "nothing was ever
+ * stored" rather than throwing, so a host can't be taken down by a browser storage restriction it
+ * doesn't control. */
+export declare function localStorageAdapter(prefix?: string): KeyValueStore;
+/** For tests, or a short-lived context with no real persistence -- state lives only as long as
+ * this object does. */
+export declare function inMemoryAdapter(): KeyValueStore;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C;mEACmE;AACnE,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,MAAM,CAAC,OAAO,CAAC,WAAkC,GAAG,aAAa,CAa3G;AAED;;;sBAGsB;AACtB,wBAAgB,mBAAmB,CAAC,MAAM,SAAK,GAAG,aAAa,CAyB9D;AAED;uBACuB;AACvB,wBAAgB,eAAe,IAAI,aAAa,CAa/C"}

package/dist/adapters.js

@@ -0,0 +1,68 @@
+// Ready-made `KeyValueStore` adapters for the two hosts this SDK is known to run in. Pass one to
+// `configureOotleStorage()` once at startup; write your own for any other host (see the interface
+// in storage.ts -- it's three methods).
+/** For a Chrome (or any Manifest V3) extension. `chrome.storage.local` already stores structured
+ * values natively, so this is a thin wrapper, not a serializer. */
+export function chromeStorageAdapter(area = chrome.storage.local) {
+    return {
+        async get(key) {
+            const stored = await area.get(key);
+            return stored[key];
+        },
+        async set(key, value) {
+            await area.set({ [key]: value });
+        },
+        async remove(key) {
+            await area.remove(key);
+        },
+    };
+}
+/** For a plain web page. `localStorage` only stores strings, so this serializes to/from JSON;
+ * unavailable or over quota (private browsing, storage disabled) degrades to "nothing was ever
+ * stored" rather than throwing, so a host can't be taken down by a browser storage restriction it
+ * doesn't control. */
+export function localStorageAdapter(prefix = "") {
+    return {
+        async get(key) {
+            try {
+                const raw = localStorage.getItem(prefix + key);
+                return raw === null ? undefined : JSON.parse(raw);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async set(key, value) {
+            try {
+                localStorage.setItem(prefix + key, JSON.stringify(value));
+            }
+            catch {
+                /* quota or disabled storage -- the in-flight operation still completes in memory */
+            }
+        },
+        async remove(key) {
+            try {
+                localStorage.removeItem(prefix + key);
+            }
+            catch {
+                /* nothing to do */
+            }
+        },
+    };
+}
+/** For tests, or a short-lived context with no real persistence -- state lives only as long as
+ * this object does. */
+export function inMemoryAdapter() {
+    const map = new Map();
+    return {
+        async get(key) {
+            return map.get(key);
+        },
+        async set(key, value) {
+            map.set(key, value);
+        },
+        async remove(key) {
+            map.delete(key);
+        },
+    };
+}

package/dist/componentAddress.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Derives an Ootle on-chain component address from a template address and an owner public key,
+ * reproducing `derive_component_address_from_public_key` (`crates/engine_types/src/component.rs`,
+ * tari-project/tari-ootle) byte-for-byte:
+ *
+ *   Blake2b-256( domain_separation_tag("com.tari.ootle.engine", v0, "ComponentAddress")
+ *              ‖ template_address (32 raw bytes, Borsh array encoding — no length prefix)
+ *              ‖ borsh_len_u32_le(32) ‖ public_key (32 bytes) )
+ *
+ * The public key is Borsh-*slice*-encoded (`RistrettoPublicKeyBytes`'s manual `BorshSerialize` impl
+ * delegates to `self.as_bytes(): &[u8]`, which Borsh length-prefixes), unlike `template_address`
+ * (`Hash32([u8; 32])`, a fixed array — Borsh does not prefix fixed-size arrays). Verified against all
+ * three committed golden vectors in `tari-ootle`'s `crates/ootle_sdk_core/fixtures/address_derive/`.
+ */
+export declare function deriveComponentAddress(templateAddress: Uint8Array, publicKey: Uint8Array): string;
+/** The builtin Account template's address: 32 zero bytes (`ACCOUNT_TEMPLATE_ADDRESS` in `tari_template_builtin`). */
+export declare const ACCOUNT_TEMPLATE_ADDRESS: Uint8Array<ArrayBuffer>;
+export declare function deriveAccountComponentAddress(publicKey: Uint8Array): string;
+/**
+ * Derives a recipient's on-chain account component address directly from their bech32m Ootle wallet
+ * address ("otl_..."). The wallet address already encodes the owner (spending) public key that
+ * `deriveAccountComponentAddress` derives the component address from -- the two identify the same
+ * account -- so callers (e.g. the Send flow) only need to collect one address from the user instead
+ * of also asking them to separately look up and paste their own `component_...` address.
+ */
+export declare function componentAddressFromWalletAddress(walletAddress: string): string;
+//# sourceMappingURL=componentAddress.d.ts.map

package/dist/componentAddress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"componentAddress.d.ts","sourceRoot":"","sources":["../src/componentAddress.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,MAAM,CAcjG;AAED,qHAAqH;AACrH,eAAO,MAAM,wBAAwB,yBAAqB,CAAC;AAE3D,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAE3E;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAG/E"}

package/dist/componentAddress.js

@@ -0,0 +1,68 @@
+import { blake2b } from "@noble/hashes/blake2.js";
+import { concatBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { parseOotleAddress } from "@tari-project/ootle-wasm";
+/**
+ * Derives an Ootle on-chain component address from a template address and an owner public key,
+ * reproducing `derive_component_address_from_public_key` (`crates/engine_types/src/component.rs`,
+ * tari-project/tari-ootle) byte-for-byte:
+ *
+ *   Blake2b-256( domain_separation_tag("com.tari.ootle.engine", v0, "ComponentAddress")
+ *              ‖ template_address (32 raw bytes, Borsh array encoding — no length prefix)
+ *              ‖ borsh_len_u32_le(32) ‖ public_key (32 bytes) )
+ *
+ * The public key is Borsh-*slice*-encoded (`RistrettoPublicKeyBytes`'s manual `BorshSerialize` impl
+ * delegates to `self.as_bytes(): &[u8]`, which Borsh length-prefixes), unlike `template_address`
+ * (`Hash32([u8; 32])`, a fixed array — Borsh does not prefix fixed-size arrays). Verified against all
+ * three committed golden vectors in `tari-ootle`'s `crates/ootle_sdk_core/fixtures/address_derive/`.
+ */
+export function deriveComponentAddress(templateAddress, publicKey) {
+    if (templateAddress.length !== 32)
+        throw new Error("templateAddress must be 32 bytes");
+    if (publicKey.length !== 32)
+        throw new Error("publicKey must be 32 bytes");
+    const domain = "com.tari.ootle.engine";
+    const version = "0";
+    const label = "ComponentAddress";
+    const tag = utf8ToBytes(`${domain}.v${version}.${label}`);
+    const digest = blake2b(concatBytes(u64le(tag.length), tag, templateAddress, u32le(publicKey.length), publicKey), { dkLen: 32 });
+    return `component_${bytesToHex(digest)}`;
+}
+/** The builtin Account template's address: 32 zero bytes (`ACCOUNT_TEMPLATE_ADDRESS` in `tari_template_builtin`). */
+export const ACCOUNT_TEMPLATE_ADDRESS = new Uint8Array(32);
+export function deriveAccountComponentAddress(publicKey) {
+    return deriveComponentAddress(ACCOUNT_TEMPLATE_ADDRESS, publicKey);
+}
+/**
+ * Derives a recipient's on-chain account component address directly from their bech32m Ootle wallet
+ * address ("otl_..."). The wallet address already encodes the owner (spending) public key that
+ * `deriveAccountComponentAddress` derives the component address from -- the two identify the same
+ * account -- so callers (e.g. the Send flow) only need to collect one address from the user instead
+ * of also asking them to separately look up and paste their own `component_...` address.
+ */
+export function componentAddressFromWalletAddress(walletAddress) {
+    const { owner_key } = parseOotleAddress(walletAddress);
+    return deriveAccountComponentAddress(owner_key);
+}
+function u32le(n) {
+    const b = new Uint8Array(4);
+    b[0] = n & 0xff;
+    b[1] = (n >>> 8) & 0xff;
+    b[2] = (n >>> 16) & 0xff;
+    b[3] = (n >>> 24) & 0xff;
+    return b;
+}
+function u64le(n) {
+    const b = new Uint8Array(8);
+    let v = BigInt(n);
+    for (let i = 0; i < 8; i++) {
+        b[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return b;
+}
+function bytesToHex(bytes) {
+    let out = "";
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, "0");
+    return out;
+}

package/dist/confidential.d.ts

@@ -0,0 +1,50 @@
+import { type StealthCryptoProvider } from "@tari-project/ootle";
+import type { OutputBody, TransactionEntry } from "@tari-project/ootle-ts-bindings";
+export interface ConfidentialSumResult {
+    /** Total plaintext value recovered across every commitment this account could decrypt. */
+    total: bigint;
+    /** Commitments that failed to decrypt against this account's view key -- expected to be 0 for
+     * a vault's own commitments map (every entry there should be ours), so a nonzero count here is
+     * worth surfacing rather than silently swallowing. */
+    failedCount: number;
+}
+/**
+ * Sums the hidden value across every commitment in a vault's `Confidential.commitments` map.
+ * Each `OutputBody` is decrypted independently -- one failing (e.g. a commitment this account
+ * doesn't actually own) is counted rather than aborting the whole sum, so a single bad entry
+ * can't hide the rest of a real balance.
+ */
+export declare function sumConfidentialCommitments(crypto: StealthCryptoProvider, viewSecret: Uint8Array, commitments: Record<string, OutputBody>): Promise<ConfidentialSumResult>;
+export interface ScannedStealthOutput {
+    resourceAddress: string;
+    /** 32-byte Pedersen commitment, hex. */
+    commitment: string;
+    amount: bigint;
+    transactionId: string;
+    /** The output's memo, if the sender attached one, as the raw JSON-encoded `Memo` union string
+     * `DecryptedData.memo` returns (see the SDK's own doc comment -- not plain text yet; callers use
+     * wallet.ts's `fromMemo()` to decode it). Decrypted alongside the amount, unlike
+     * `sumConfidentialCommitments`, which passes `skipMemo: true` since it only needs a running total. */
+    memo?: string;
+}
+/**
+ * Walks a batch of `TransactionEntry`s (as returned by the indexer's `listRecentTransactions`)
+ * looking for `StealthTransfer` instructions, and tries to decrypt each output against this
+ * account's own view key -- the client-side half of the "scan new outputs" step described at
+ * ootle.tari.com/guides/stealth-resources, which nothing in the SDK wraps end-to-end today.
+ *
+ * A *pruned* transaction (what `listRecentTransactions` returns) only omits large blob payloads
+ * (template code, etc.) -- confirmed by reading the wire types, not assumed: instruction fields,
+ * including a `StealthTransfer`'s full `outputs_statement`, are preserved verbatim. Each output
+ * there carries its commitment, sender public nonce, and encrypted data as plain hex, which is
+ * everything `decryptInputData` needs -- no further per-output substate fetch required.
+ *
+ * Skips: commitments already in `knownCommitments` (no need to re-decrypt something already
+ * recorded), and any `StealthTransfer` whose resource address is a `Workspace` reference rather
+ * than a literal `Address` -- resolving a workspace reference would mean replaying that
+ * transaction's whole instruction sequence, out of scope for a lightweight scan. This wallet's own
+ * shield/unshield/sendPrivately always emit a literal `Address`, so this only ever skips
+ * unusually-built third-party transactions.
+ */
+export declare function scanTransactionsForOwnedOutputs(crypto: StealthCryptoProvider, viewSecret: Uint8Array, transactions: TransactionEntry[], knownCommitments: ReadonlySet<string>): Promise<ScannedStealthOutput[]>;
+//# sourceMappingURL=confidential.d.ts.map

package/dist/confidential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidential.d.ts","sourceRoot":"","sources":["../src/confidential.ts"],"names":[],"mappings":"AAUA,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAGpF,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd;;0DAEsD;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,qBAAqB,EAC7B,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GACtC,OAAO,CAAC,qBAAqB,CAAC,CAgBhC;AAED,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB;;;0GAGsG;IACtG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,qBAAqB,EAC7B,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,gBAAgB,EAAE,EAChC,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,GACpC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA0BjC"}

package/dist/confidential.js

@@ -0,0 +1,86 @@
+// Decrypting the private portion of a vault's Confidential resource container -- the value
+// hidden inside Pedersen commitments (`ResourceContainer.Confidential.commitments`), readable
+// only with the account's own view key. This is a *read*, not a spend: it only interprets data
+// the caller already fetched (a vault substate), never touches the network or the account's
+// owner key, and can never move funds.
+//
+// `decryptInputData` (not `decryptOwnedUtxo`) is the correct primitive here: `decryptOwnedUtxo`
+// expects a full fetched `Utxo`-shaped substate (via `parseSubstateUtxo`), but a vault's inline
+// `commitments` map holds raw `OutputBody` values directly, with no substate wrapper -- verified
+// against `@tari-project/ootle`'s own type signatures before writing this, not assumed.
+import { decryptInputData } from "@tari-project/ootle";
+import { fromHex } from "./vault";
+/**
+ * Sums the hidden value across every commitment in a vault's `Confidential.commitments` map.
+ * Each `OutputBody` is decrypted independently -- one failing (e.g. a commitment this account
+ * doesn't actually own) is counted rather than aborting the whole sum, so a single bad entry
+ * can't hide the rest of a real balance.
+ */
+export async function sumConfidentialCommitments(crypto, viewSecret, commitments) {
+    let total = 0n;
+    let failedCount = 0;
+    for (const [commitmentHex, body] of Object.entries(commitments)) {
+        try {
+            const { value } = await decryptInputData(crypto, fromHex(commitmentHex), fromHex(body.encrypted_data), {
+                senderPublicNonce: fromHex(body.public_nonce),
+                viewSecret,
+                skipMemo: true,
+            });
+            total += value;
+        }
+        catch {
+            failedCount++;
+        }
+    }
+    return { total, failedCount };
+}
+/**
+ * Walks a batch of `TransactionEntry`s (as returned by the indexer's `listRecentTransactions`)
+ * looking for `StealthTransfer` instructions, and tries to decrypt each output against this
+ * account's own view key -- the client-side half of the "scan new outputs" step described at
+ * ootle.tari.com/guides/stealth-resources, which nothing in the SDK wraps end-to-end today.
+ *
+ * A *pruned* transaction (what `listRecentTransactions` returns) only omits large blob payloads
+ * (template code, etc.) -- confirmed by reading the wire types, not assumed: instruction fields,
+ * including a `StealthTransfer`'s full `outputs_statement`, are preserved verbatim. Each output
+ * there carries its commitment, sender public nonce, and encrypted data as plain hex, which is
+ * everything `decryptInputData` needs -- no further per-output substate fetch required.
+ *
+ * Skips: commitments already in `knownCommitments` (no need to re-decrypt something already
+ * recorded), and any `StealthTransfer` whose resource address is a `Workspace` reference rather
+ * than a literal `Address` -- resolving a workspace reference would mean replaying that
+ * transaction's whole instruction sequence, out of scope for a lightweight scan. This wallet's own
+ * shield/unshield/sendPrivately always emit a literal `Address`, so this only ever skips
+ * unusually-built third-party transactions.
+ */
+export async function scanTransactionsForOwnedOutputs(crypto, viewSecret, transactions, knownCommitments) {
+    const found = [];
+    for (const entry of transactions) {
+        const tx = entry.transaction.V1.body.transaction;
+        for (const instruction of [...tx.instructions, ...tx.fee_instructions]) {
+            if (typeof instruction === "string" || !("StealthTransfer" in instruction))
+                continue;
+            const { resource_address_ref, statement } = instruction.StealthTransfer;
+            if (!("Address" in resource_address_ref))
+                continue;
+            const resourceAddress = resource_address_ref.Address;
+            for (const stealthOutput of statement.outputs_statement.outputs) {
+                const commitmentHex = stealthOutput.output.commitment;
+                if (knownCommitments.has(commitmentHex))
+                    continue;
+                try {
+                    const { value, memo } = await decryptInputData(crypto, fromHex(commitmentHex), fromHex(stealthOutput.output.encrypted_data), {
+                        senderPublicNonce: fromHex(stealthOutput.output.sender_public_nonce),
+                        viewSecret,
+                        skipMemo: false,
+                    });
+                    found.push({ resourceAddress, commitment: commitmentHex, amount: value, transactionId: entry.transaction_id, memo });
+                }
+                catch {
+                    // Not ours.
+                }
+            }
+        }
+    }
+    return found;
+}

package/dist/derivation.d.ts

@@ -0,0 +1,7 @@
+export interface DerivedAccountKeys {
+    ownerSecret: Uint8Array;
+    viewSecret: Uint8Array;
+}
+/** `entropy` is the 16-byte CipherSeed entropy (see cipherSeed.ts), not the raw seed/mnemonic. */
+export declare function deriveAccountKeys(entropy: Uint8Array, index: number): DerivedAccountKeys;
+//# sourceMappingURL=derivation.d.ts.map

package/dist/derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivation.d.ts","sourceRoot":"","sources":["../src/derivation.ts"],"names":[],"mappings":"AA4CA,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,UAAU,CAAC;IACxB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,kGAAkG;AAClG,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAKxF"}

package/dist/derivation.js

@@ -0,0 +1,47 @@
+// HD key derivation: CipherSeed entropy + account index -> a deterministic (ownerSecret,
+// viewSecret) Ristretto scalar pair, matching the shape `SecretKeyWallet.fromSecretKey` expects
+// (owner/spend key + view-only key — the "account" / "view_only_key" branches).
+//
+// Reproduces `derive_ristretto_key` (tari-ootle's `crates/wallet/crypto/src/derive.rs`)
+// byte-for-byte: a domain-separated Blake2b-512 hash under `KeyManagerDomain`
+// (`domainHash.ts`), label `"derive_key"`, chaining `entropy ‖ branch ‖ index (u64 LE)`
+// — each individually length-prefixed by the hasher, not concatenated first — wide-reduced mod
+// the Ristretto group order. Branch strings ("account" / "view_only_key") are
+// `KeyBranch::as_str()` (tari-ootle's `crates/wallet/sdk/src/models/key.rs`).
+import { utf8ToBytes } from "@noble/hashes/utils.js";
+import { keyManagerDomainHasher } from "./domainHash";
+// The Ristretto255 / Ed25519 group order l = 2^252 + 27742317777372353535851937790883648493.
+const GROUP_ORDER = (1n << 252n) + 27742317777372353535851937790883648493n;
+function u64le(n) {
+    const b = new Uint8Array(8);
+    let v = BigInt(n);
+    for (let i = 0; i < 8; i++) {
+        b[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return b;
+}
+/** Reduce a 64-byte wide value mod the group order and re-encode as a 32-byte little-endian scalar. */
+function scalarFromWideBytes(wide) {
+    let n = 0n;
+    for (let i = wide.length - 1; i >= 0; i--)
+        n = (n << 8n) | BigInt(wide[i] ?? 0);
+    n %= GROUP_ORDER;
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        out[i] = Number(n & 0xffn);
+        n >>= 8n;
+    }
+    return out;
+}
+function deriveScalar(entropy, branch, index) {
+    const wide = keyManagerDomainHasher("derive_key", 64).chain(entropy).chain(utf8ToBytes(branch)).chain(u64le(index)).finalize();
+    return scalarFromWideBytes(wide);
+}
+/** `entropy` is the 16-byte CipherSeed entropy (see cipherSeed.ts), not the raw seed/mnemonic. */
+export function deriveAccountKeys(entropy, index) {
+    return {
+        ownerSecret: deriveScalar(entropy, "account", index),
+        viewSecret: deriveScalar(entropy, "view_only_key", index),
+    };
+}

package/dist/domainHash.d.ts

@@ -0,0 +1,11 @@
+export declare class DomainSeparatedHasher {
+    private chunks;
+    private readonly dkLen;
+    constructor(domain: string, version: number, label: string, dkLen: 32 | 64);
+    chain(data: Uint8Array): this;
+    finalize(): Uint8Array;
+}
+export declare const KEY_MANAGER_DOMAIN = "com.tari.base_layer.key_manager";
+export declare const KEY_MANAGER_DOMAIN_VERSION = 1;
+export declare function keyManagerDomainHasher(label: string, dkLen: 32 | 64): DomainSeparatedHasher;
+//# sourceMappingURL=domainHash.d.ts.map

package/dist/domainHash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domainHash.d.ts","sourceRoot":"","sources":["../src/domainHash.ts"],"names":[],"mappings":"AAyBA,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE;IAM1E,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAK7B,QAAQ,IAAI,UAAU;CAGvB;AAED,eAAO,MAAM,kBAAkB,oCAAoC,CAAC;AACpE,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,GAAG,qBAAqB,CAE3F"}

package/dist/domainHash.js

@@ -0,0 +1,44 @@
+// Reproduces `tari_crypto::hashing::DomainSeparatedHasher<Blake2b<N>, Domain>` byte-for-byte
+// (tari-crypto v0.23.2 `src/hashing.rs`), used by both CipherSeed (cipherSeed.ts) and account-key
+// derivation (derivation.ts), which both hash under `KeyManagerDomain` — `("com.tari.base_layer.key
+// _manager", version 1)`, per `tari_hashing` v5.5.0 `hashing/src/domains.rs`.
+//
+// `new_with_label(label)` seeds the digest with `u64LE(tag.len()) ‖ tag`, where
+// `tag = "{domain}.v{version}.{label}"`. Every subsequent `.chain(data)` call adds its OWN
+// `u64LE(data.len()) ‖ data` — every chained field is individually length-prefixed, not just the
+// initial tag. `DomainSeparatedHasher` is generic over the domain, so this class takes
+// domain/version as constructor args too — domainHash.test.ts checks it against tari-crypto's own
+// committed test vectors, which use a different domain ("com.tari.generic") than the one this
+// codebase actually needs.
+import { blake2b } from "@noble/hashes/blake2.js";
+import { concatBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+function u64le(n) {
+    const b = new Uint8Array(8);
+    let v = BigInt(n);
+    for (let i = 0; i < 8; i++) {
+        b[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return b;
+}
+export class DomainSeparatedHasher {
+    chunks;
+    dkLen;
+    constructor(domain, version, label, dkLen) {
+        this.dkLen = dkLen;
+        const tag = utf8ToBytes(label ? `${domain}.v${version}.${label}` : `${domain}.v${version}`);
+        this.chunks = [u64le(tag.length), tag];
+    }
+    chain(data) {
+        this.chunks.push(u64le(data.length), data);
+        return this;
+    }
+    finalize() {
+        return blake2b(concatBytes(...this.chunks), { dkLen: this.dkLen });
+    }
+}
+export const KEY_MANAGER_DOMAIN = "com.tari.base_layer.key_manager";
+export const KEY_MANAGER_DOMAIN_VERSION = 1;
+export function keyManagerDomainHasher(label, dkLen) {
+    return new DomainSeparatedHasher(KEY_MANAGER_DOMAIN, KEY_MANAGER_DOMAIN_VERSION, label, dkLen);
+}

package/dist/htlc.d.ts

@@ -0,0 +1,26 @@
+/** An `AccessRule` satisfied only by a transaction signed with `publicKeyHex` (32 raw bytes, hex). */
+export declare function accessRuleRequiringPublicKey(publicKeyHex: string): object;
+export interface HtlcConditionsParams {
+    /** SHA-256 digest of the secret preimage, as 32 bytes hex. The party funding the HTLC never
+     * needs (and should never be given) the preimage itself -- only this hash. */
+    hashLockHex: string;
+    /** The epoch at/after which the refund path becomes admissible, and strictly before which the
+     * claim path is admissible -- so exactly one of the two leaves is ever satisfiable at a given
+     * epoch. Must fit a JS safe integer (real network epochs are nowhere near 2^53). */
+    refundEpoch: bigint;
+    /** The claimant's raw 32-byte owner public key, hex. */
+    claimantPublicKeyHex: string;
+    /** The refunder's (funder's own) raw 32-byte owner public key, hex. */
+    refunderPublicKeyHex: string;
+}
+/** The two-leaf HTLC condition tree, `[claimLeaf, refundLeaf]` -- pass directly as
+ * `createOutput({ payTo: { Conditions: htlcConditions(...) }, ... })`.
+ *
+ * Claim leaf: hashlock AND before the refund epoch AND the claimant's key.
+ * Refund leaf: at/after the refund epoch AND the refunder's key.
+ *
+ * The condition tree's root (computed on-chain from these leaves at output-creation time) is all
+ * that's committed publicly; these full leaves must be handed to the claimant out of band (e.g. by
+ * the swap protocol/dApp) so they can later reveal the claim leaf via `buildScriptPathWitness`. */
+export declare function htlcConditions(params: HtlcConditionsParams): object[];
+//# sourceMappingURL=htlc.d.ts.map

package/dist/htlc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"htlc.d.ts","sourceRoot":"","sources":["../src/htlc.ts"],"names":[],"mappings":"AAoBA,sGAAsG;AACtG,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAazE;AAED,MAAM,WAAW,oBAAoB;IACnC;kFAC8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB;;wFAEoF;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;mGAQmG;AACnG,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,EAAE,CA0BrE"}