@chironbuilder/ootle-sdk 0.1.30 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/dist/bucketStealthTransfer.d.ts +12 -0
  2. package/dist/bucketStealthTransfer.d.ts.map +1 -0
  3. package/dist/bucketStealthTransfer.js +57 -0
  4. package/dist/indexerDecode.d.ts +23 -0
  5. package/dist/indexerDecode.d.ts.map +1 -0
  6. package/dist/indexerDecode.js +68 -0
  7. package/dist/utxoScan.d.ts +24 -39
  8. package/dist/utxoScan.d.ts.map +1 -1
  9. package/dist/utxoScan.js +136 -133
  10. package/dist/wallet.d.ts +7 -8
  11. package/dist/wallet.d.ts.map +1 -1
  12. package/dist/wallet.js +70 -70
  13. package/package.json +8 -8
  14. package/vendor/ootle-wasm-patched/chiron-0.49.2.patch +199 -0
  15. package/vendor/ootle-wasm-patched/ootle_wasm.d.ts +53 -35
  16. package/vendor/ootle-wasm-patched/ootle_wasm.js +1 -1
  17. package/vendor/ootle-wasm-patched/ootle_wasm_bg.js +158 -45
  18. package/vendor/ootle-wasm-patched/ootle_wasm_bg.wasm +0 -0
  19. package/vendor/ootle-wasm-patched/ootle_wasm_bg.wasm.d.ts +15 -12
  20. package/vendor/ootle-wasm-patched/package.json +3 -3
  21. package/vendor/ootle-patched/README.md +0 -67
  22. package/vendor/ootle-patched/dist/index.d.ts +0 -2158
  23. package/vendor/ootle-patched/dist/index.js +0 -1389
  24. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/README.md +0 -128
  25. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/ootle_wasm.d.ts +0 -436
  26. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/ootle_wasm.js +0 -9
  27. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/ootle_wasm_bg.js +0 -1450
  28. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/ootle_wasm_bg.wasm +0 -0
  29. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/package.json +0 -30
  30. package/vendor/ootle-patched/package.json +0 -23
@@ -0,0 +1,12 @@
1
+ import { StealthTransfer } from "@tari-project/ootle";
2
+ import type { Instruction } from "@tari-project/ootle-ts-bindings";
3
+ export declare class BucketStealthTransfer extends StealthTransfer {
4
+ private bucketVar;
5
+ private followUps;
6
+ /** Reveal `amount` to `receiver` and keep it on the workspace as `workspaceVarName`. */
7
+ toRevealedOutputAsBucket(amount: bigint, workspaceVarName: string, receiver: Uint8Array): this;
8
+ /** Instructions appended after the stealth transfer (they may reference the bucket). */
9
+ andThen(instructions: Instruction[]): this;
10
+ constructor(...args: ConstructorParameters<typeof StealthTransfer>);
11
+ }
12
+ //# sourceMappingURL=bucketStealthTransfer.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bucketStealthTransfer.d.ts","sourceRoot":"","sources":["../src/bucketStealthTransfer.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAanE,qBAAa,qBAAsB,SAAQ,eAAe;IACxD,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,SAAS,CAAqB;IAEtC,wFAAwF;IACxF,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,GAAG,IAAI;IAQ9F,wFAAwF;IACxF,OAAO,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,IAAI;gBAK9B,GAAG,IAAI,EAAE,qBAAqB,CAAC,OAAO,eAAe,CAAC;CAuBnE"}
@@ -0,0 +1,57 @@
1
+ // A `StealthTransfer` whose revealed output is left on the workspace as a named bucket (instead of
2
+ // being deposited back into the source account), followed by caller-supplied instructions that
3
+ // consume it in the same transaction. This is what `withdrawStealthAndExecute` needs; upstream
4
+ // `@tari-project/ootle` only offers `toRevealedOutput`, which always deposits the revealed amount.
5
+ //
6
+ // Replaces the vendored ootle.ts 0.3 fork (`@chironbuilder/ootle-legacy`): everything except the
7
+ // final "what happens to the revealed bucket" step is the upstream builder's own code, so the
8
+ // statement / input / signer handling tracks upstream releases automatically.
9
+ import { StealthTransfer } from "@tari-project/ootle";
10
+ // `emitInstructions` is a (TS-)private method of the upstream class; reach it via the prototype.
11
+ const baseEmit = StealthTransfer.prototype.emitInstructions;
12
+ if (typeof baseEmit !== "function") {
13
+ throw new Error("@tari-project/ootle StealthTransfer no longer has emitInstructions(); BucketStealthTransfer needs updating");
14
+ }
15
+ export class BucketStealthTransfer extends StealthTransfer {
16
+ bucketVar = null;
17
+ followUps = [];
18
+ /** Reveal `amount` to `receiver` and keep it on the workspace as `workspaceVarName`. */
19
+ toRevealedOutputAsBucket(amount, workspaceVarName, receiver) {
20
+ if (this.bucketVar !== null && this.bucketVar !== workspaceVarName) {
21
+ throw new Error(`toRevealedOutputAsBucket: already saving to "${this.bucketVar}"`);
22
+ }
23
+ this.bucketVar = workspaceVarName;
24
+ return this.toRevealedOutput(amount, receiver);
25
+ }
26
+ /** Instructions appended after the stealth transfer (they may reference the bucket). */
27
+ andThen(instructions) {
28
+ this.followUps.push(...instructions);
29
+ return this;
30
+ }
31
+ constructor(...args) {
32
+ super(...args);
33
+ // Shadow the upstream (TS-private) emitInstructions on this instance: emit withdraw +
34
+ // StealthTransfer exactly as upstream, minus its trailing deposit, then save the bucket.
35
+ Object.defineProperty(this, "emitInstructions", {
36
+ value: (statement) => {
37
+ const self = this;
38
+ if (this.bucketVar === null) {
39
+ baseEmit.call(this, statement);
40
+ }
41
+ else {
42
+ const saved = self.state.revealedOutput;
43
+ self.state.revealedOutput = null;
44
+ try {
45
+ baseEmit.call(this, statement);
46
+ }
47
+ finally {
48
+ self.state.revealedOutput = saved;
49
+ }
50
+ self.builder.saveVar(this.bucketVar);
51
+ }
52
+ if (this.followUps.length > 0)
53
+ self.builder.withInstructions(this.followUps);
54
+ },
55
+ });
56
+ }
57
+ }
@@ -0,0 +1,23 @@
1
+ import type { IndexerProvider } from "@tari-project/ootle-indexer";
2
+ /** Decodes a substate value if it is a base64 CBOR string; returns objects unchanged. */
3
+ export declare function substateValueOf<T = any>(value: unknown): T;
4
+ /** Decodes an `ExecuteResult` if it is a base64 CBOR string; returns objects/null unchanged. */
5
+ export declare function executeResultOf<T = any>(value: unknown): T;
6
+ export declare function eventOf<T = any>(value: unknown): T;
7
+ export declare function utxoValueOf<T = any>(value: unknown): T;
8
+ /** `getSubstate` response with `state.up.substate` decoded. */
9
+ export declare function decodeSubstateResponse<T = any>(response: any): T;
10
+ export declare function getSubstateDecoded(provider: IndexerProvider, substateId: string, version?: number | null): Promise<any>;
11
+ /** `fetchSubstates` with each entry given the pre-0.48 `{ version, substate }` shape. */
12
+ export declare function fetchSubstatesDecoded(provider: IndexerProvider, ids: string[]): Promise<{
13
+ substates: Record<string, {
14
+ version: number;
15
+ substate: any;
16
+ } | undefined>;
17
+ }>;
18
+ /** Decodes `Finalized.execution_result` (and nested event blobs) in a transaction-result response. */
19
+ export declare function decodeTransactionResultResponse<T = any>(response: any): T;
20
+ /** An `ExecuteResult` with any CBOR-string events also decoded. */
21
+ export declare function decodeExecuteResultDeep<T = any>(value: unknown): T;
22
+ export declare function getTransactionResultDecoded(provider: IndexerProvider, transactionId: string): Promise<any>;
23
+ //# sourceMappingURL=indexerDecode.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"indexerDecode.d.ts","sourceRoot":"","sources":["../src/indexerDecode.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAE1D;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAE1D;AAED,wBAAgB,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAElD;AAED,wBAAgB,WAAW,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAEtD;AAED,+DAA+D;AAC/D,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,GAAG,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC,CAKhE;AAED,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAE7H;AAED,yFAAyF;AACzF,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,GAAG,CAAA;KAAE,GAAG,SAAS,CAAC,CAAA;CAAE,CAAC,CAQ5K;AAED,sGAAsG;AACtG,wBAAgB,+BAA+B,CAAC,CAAC,GAAG,GAAG,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC,CAUzE;AAED,mEAAmE;AACnE,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAOlE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAEhH"}
@@ -0,0 +1,68 @@
1
+ // Ootle 0.48+ indexers serve substate values, execution results, events and UTXOs as base64 CBOR
2
+ // blobs (tari-ootle #3100/#3101/#3110). The SDK's own readers were written against the decoded
3
+ // JSON shapes, so every internal read goes through these helpers, which decode once and hand back
4
+ // the pre-0.48 shape. Values that are already objects (an older JSON indexer) pass through, so the
5
+ // helpers are safe against either server.
6
+ //
7
+ // Upstream `@tari-project/ootle` code (StealthTransfer, resolveTransaction, ...) is still handed
8
+ // the raw provider: it expects the encoded shapes itself.
9
+ import { decodeEvent, decodeExecuteResult, decodeSubstateValue, decodeUtxo } from "@tari-project/ootle";
10
+ /** Decodes a substate value if it is a base64 CBOR string; returns objects unchanged. */
11
+ export function substateValueOf(value) {
12
+ return (typeof value === "string" ? decodeSubstateValue(value) : value);
13
+ }
14
+ /** Decodes an `ExecuteResult` if it is a base64 CBOR string; returns objects/null unchanged. */
15
+ export function executeResultOf(value) {
16
+ return (typeof value === "string" ? decodeExecuteResult(value) : value);
17
+ }
18
+ export function eventOf(value) {
19
+ return (typeof value === "string" ? decodeEvent(value) : value);
20
+ }
21
+ export function utxoValueOf(value) {
22
+ return (typeof value === "string" ? decodeUtxo(value) : value);
23
+ }
24
+ /** `getSubstate` response with `state.up.substate` decoded. */
25
+ export function decodeSubstateResponse(response) {
26
+ if (response && response.state && typeof response.state === "object" && "up" in response.state) {
27
+ return { ...response, state: { up: { ...response.state.up, substate: substateValueOf(response.state.up.substate) } } };
28
+ }
29
+ return response;
30
+ }
31
+ export async function getSubstateDecoded(provider, substateId, version) {
32
+ return decodeSubstateResponse(await provider.getSubstate(substateId, version));
33
+ }
34
+ /** `fetchSubstates` with each entry given the pre-0.48 `{ version, substate }` shape. */
35
+ export async function fetchSubstatesDecoded(provider, ids) {
36
+ const response = (await provider.fetchSubstates(ids));
37
+ const substates = {};
38
+ for (const [id, entry] of Object.entries(response.substates ?? {})) {
39
+ if (!entry)
40
+ continue;
41
+ substates[id] = { ...entry, substate: substateValueOf(entry.value ?? entry.substate) };
42
+ }
43
+ return { ...response, substates };
44
+ }
45
+ /** Decodes `Finalized.execution_result` (and nested event blobs) in a transaction-result response. */
46
+ export function decodeTransactionResultResponse(response) {
47
+ const result = response?.result;
48
+ if (result && typeof result === "object" && "Finalized" in result) {
49
+ const finalized = result.Finalized;
50
+ return {
51
+ ...response,
52
+ result: { Finalized: { ...finalized, execution_result: decodeExecuteResultDeep(finalized.execution_result) } },
53
+ };
54
+ }
55
+ return response;
56
+ }
57
+ /** An `ExecuteResult` with any CBOR-string events also decoded. */
58
+ export function decodeExecuteResultDeep(value) {
59
+ const decoded = executeResultOf(value);
60
+ const events = decoded?.finalize?.events;
61
+ if (Array.isArray(events) && events.some((e) => typeof e === "string")) {
62
+ return { ...decoded, finalize: { ...decoded.finalize, events: events.map(eventOf) } };
63
+ }
64
+ return decoded;
65
+ }
66
+ export async function getTransactionResultDecoded(provider, transactionId) {
67
+ return decodeTransactionResultResponse(await provider.getTransactionResult(transactionId));
68
+ }
@@ -1,8 +1,10 @@
1
1
  import { type StealthCryptoProvider } from "@tari-project/ootle";
2
- import type { Shard, StateVersion } from "@tari-project/ootle-ts-bindings";
2
+ import type { Shard, StateVersion, UtxoTag } from "@tari-project/ootle-ts-bindings";
3
3
  import type { ScannedStealthOutput } from "./confidential.js";
4
+ /** Shards 1..=NUM_PRESHARDS (shard 0 is the global shard, which holds no UTXOs). */
5
+ export declare const NUM_PRESHARDS = 256;
4
6
  /** Checkpoint for one resource's delta scan: a `[Shard, StateVersion]` pair per shard read so far.
5
- * Serialize as JSON; pass back verbatim as `shard_state_versions` on the next call. */
7
+ * Serialize as JSON; pass back verbatim on the next call. Empty = scan every shard from genesis. */
6
8
  export type UtxoScanWatermark = Array<[Shard, StateVersion]>;
7
9
  /** Result of a delta scan (`scanUtxosDelta`). */
8
10
  export interface UtxosDeltaResult {
@@ -17,52 +19,35 @@ export interface UtxosDeltaResult {
17
19
  * Call `scanUtxosDelta` again (with the returned `watermarks`) until this is false. */
18
20
  hasMore: boolean;
19
21
  }
20
- /** Result of one page of a full paginated scan (`scanUtxosPage`). */
22
+ /** Result of one pass of a full scan (`scanUtxosPage`). */
21
23
  export interface UtxosPageResult {
22
24
  /** Outputs we decrypted as ours. Pass each to `addShieldedOutput`. */
23
25
  owned: ScannedStealthOutput[];
24
- /** Cursor for the next page. Save it with `setUtxoScanPageCursor` and pass as `fromId` on
25
- * the next call. `null` means this was the last page. */
26
+ /** Opaque cursor for the next pass (save with `setUtxoScanPageCursor`, pass as `fromId`).
27
+ * `null` means the sweep reached the end of every shard. */
26
28
  nextCursor: string | null;
27
29
  }
30
+ interface StreamRead {
31
+ unspent: Array<[UtxoTag, string]>;
32
+ spent: string[];
33
+ reached: Map<number, StateVersion>;
34
+ hasMore: boolean;
35
+ }
36
+ /** Every shard at version 0 — the request a first scan sends. */
37
+ export declare function genesisWatermarks(): UtxoScanWatermark;
38
+ /** Parses an ndjson UTXO stream body into updates and per-shard resume points. */
39
+ export declare function parseUtxoStream(body: string): StreamRead;
28
40
  /**
29
- * Fetches all UTXO updates (new outputs + spends) since the given watermarks from the indexer's
30
- * streaming endpoint, then decrypts any `Unspent` candidates with the account's view key.
31
- *
32
- * Pass `watermarks: []` (or the saved value from storage) on every call. The very first call
33
- * with an empty watermarks array replays everything the indexer has retained, so it doubles as the
34
- * initial full scan. Subsequent calls with the returned watermarks fetch only the delta.
35
- *
36
- * Call in a loop until `result.hasMore` is false:
37
- * ```ts
38
- * let wm = await getUtxoScanWatermarks(accountId, resourceAddress);
39
- * do {
40
- * const r = await scanUtxosDelta(indexerUrl, resourceAddress, crypto, viewSecret, wm, 200);
41
- * for (const o of r.owned) await addShieldedOutput({ ...o, accountId, ... });
42
- * for (const c of r.spentCommitments) await markShieldedOutputSpent(accountId, c);
43
- * wm = r.watermarks;
44
- * await setUtxoScanWatermarks(accountId, resourceAddress, wm);
45
- * } while (r.hasMore);
46
- * ```
41
+ * Reads UTXO updates (new outputs + spends) since `watermarks` and decrypts the new outputs with
42
+ * the account's view key. Pass `[]` (or the saved value) on every call; call again with the
43
+ * returned watermarks until `hasMore` is false.
47
44
  */
48
45
  export declare function scanUtxosDelta(indexerBaseUrl: string, resourceAddress: string, crypto: StealthCryptoProvider, viewSecret: Uint8Array, watermarks: UtxoScanWatermark, perShardLimit?: number): Promise<UtxosDeltaResult>;
49
46
  /**
50
- * Fetches one page of the live UTXO set for a resource and tries to decrypt each output.
51
- *
52
- * Use this when the watermarks are lost or a full re-scan is needed. The `fromId` cursor is the
53
- * `UtxoId` (32-byte commitment hex) of the last output seen on the previous page.
54
- *
55
- * Call in a loop until `result.nextCursor` is null:
56
- * ```ts
57
- * let cursor = await getUtxoScanPageCursor(accountId, resourceAddress);
58
- * do {
59
- * const r = await scanUtxosPage(indexerUrl, resourceAddress, crypto, viewSecret, cursor);
60
- * for (const o of r.owned) await addShieldedOutput({ ...o, accountId, ... });
61
- * cursor = r.nextCursor;
62
- * if (cursor) await setUtxoScanPageCursor(accountId, resourceAddress, cursor);
63
- * } while (cursor !== null);
64
- * await clearUtxoScanPageCursor(accountId, resourceAddress);
65
- * ```
47
+ * One pass of a sweep over every live UTXO of `resourceAddress`. `fromId` is the cursor a previous
48
+ * pass returned (`null` starts a new sweep); a cursor from the pre-0.48 `GET /utxos` API (a bare
49
+ * UtxoId) is ignored and the sweep restarts.
66
50
  */
67
51
  export declare function scanUtxosPage(indexerBaseUrl: string, resourceAddress: string, crypto: StealthCryptoProvider, viewSecret: Uint8Array, fromId?: string | null, pageSize?: number): Promise<UtxosPageResult>;
52
+ export {};
68
53
  //# sourceMappingURL=utxoScan.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"utxoScan.d.ts","sourceRoot":"","sources":["../src/utxoScan.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAA2C,MAAM,iCAAiC,CAAC;AAGpH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAuC9D;uFACuF;AACvF,MAAM,MAAM,iBAAiB,GAAG,KAAK,CAAC,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC;AAE7D,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B;iDAC6C;IAC7C,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,UAAU,EAAE,iBAAiB,CAAC;IAC9B;2FACuF;IACvF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B;8DAC0D;IAC1D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA+DD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAClC,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,qBAAqB,EAC7B,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,iBAAiB,EAC7B,aAAa,SAAM,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAiD3B;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CACjC,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,qBAAqB,EAC7B,UAAU,EAAE,UAAU,EACtB,MAAM,GAAE,MAAM,GAAG,IAAW,EAC5B,QAAQ,SAAM,GACb,OAAO,CAAC,eAAe,CAAC,CAoB1B"}
1
+ {"version":3,"file":"utxoScan.d.ts","sourceRoot":"","sources":["../src/utxoScan.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAgC,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAU,OAAO,EAAQ,MAAM,iCAAiC,CAAC;AAElG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,oFAAoF;AACpF,eAAO,MAAM,aAAa,MAAM,CAAC;AAGjC;oGACoG;AACpG,MAAM,MAAM,iBAAiB,GAAG,KAAK,CAAC,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC;AAE7D,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B;iDAC6C;IAC7C,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,UAAU,EAAE,iBAAiB,CAAC;IAC9B;2FACuF;IACvF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B;gEAC4D;IAC5D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAYD,UAAU,UAAU;IAClB,OAAO,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,iEAAiE;AACjE,wBAAgB,iBAAiB,IAAI,iBAAiB,CAErD;AAMD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAkBxD;AAuGD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,qBAAqB,EAC7B,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,iBAAiB,EAC7B,aAAa,SAAM,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAI3B;AAID;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,qBAAqB,EAC7B,UAAU,EAAE,UAAU,EACtB,MAAM,GAAE,MAAM,GAAG,IAAW,EAC5B,QAAQ,SAAM,GACb,OAAO,CAAC,eAAe,CAAC,CAa1B"}
package/dist/utxoScan.js CHANGED
@@ -1,48 +1,114 @@
1
- // Scan the live UTXO set for stealth outputs owned by this account's view key.
1
+ // UTXO-based stealth output discovery against the Ootle 0.48+ indexer REST API.
2
2
  //
3
- // Two complementary strategies:
3
+ // scanUtxosDelta — incremental, checkpoint-based (POST /utxos/stream). Given per-shard state
4
+ // version watermarks (empty = every shard from genesis), reads the next
5
+ // `per_shard_limit` rows of each shard: new outputs (tag + public nonce) and
6
+ // spends/burns. Candidate outputs are fetched in full (POST /utxos/fetch) and
7
+ // trial-decrypted with the view key.
8
+ // scanUtxosPage — "full" scan. 0.48 removed `GET /utxos`, so this is the same stream read with
9
+ // `unspent_only: true`, its watermarks carried in an opaque string cursor. It
10
+ // finds every live output; it reports no spends.
4
11
  //
5
- // scanUtxosDelta — incremental, checkpoint-based (POST /utxos/stream). Given the watermarks
6
- // saved from the last call, returns only new/spent outputs since then. Pass
7
- // empty watermarks for the first call; the indexer will replay the full set.
8
- // Also handles `Spent` / `Burnt` updates so the caller can mark old outputs
9
- // as spent without polling individual substates.
10
- //
11
- // scanUtxosPage — paginated full scan (GET /utxos). Fetches one page of the current UTXO
12
- // set ordered by commitment id. Use the returned `nextCursor` for the next
13
- // call. Useful for first-time imports or recovery when the watermarks are lost.
14
- //
15
- // The two share the same decryption helper. `ScannedStealthOutput` (defined in confidential.ts)
16
- // is the output type passed to `addShieldedOutput` in storage.ts.
17
- import { decryptInputData } from "@tari-project/ootle";
18
- import { fromHex } from "./vault.js";
19
- // ── helpers ───────────────────────────────────────────────────────────────────────────────────────
20
- async function postJson(baseUrl, path, body) {
21
- const url = baseUrl.replace(/\/$/, "") + "/" + path;
22
- const resp = await fetch(url, {
12
+ // Wire format (tari-ootle v0.49 `rest_api/streaming/utxo_stream.rs`): the stream answers
13
+ // `application/x-ndjson` with one `UtxoUpdatePayload` per line —
14
+ // { "sos": { shard, max_state_version, num_updates, has_more, spends_incomplete } | null,
15
+ // "update": { "Unspent": { tag, public_nonce: number[] } } | { "Spent": { id: number[], version } }
16
+ // | { "Burnt": { id: number[], version } } | null,
17
+ // "eos": { max_state_version } | null }
18
+ // A request that names no shards reads nothing, so a first scan names every shard at version 0.
19
+ // `/utxos/fetch` answers `{ utxos: [UtxoId, base64-CBOR Utxo][], spent, next_cursor? }`.
20
+ import { decryptInputData, decodeUtxo } from "@tari-project/ootle";
21
+ import { fromHex, toHex } from "./vault.js";
22
+ /** Shards 1..=NUM_PRESHARDS (shard 0 is the global shard, which holds no UTXOs). */
23
+ export const NUM_PRESHARDS = 256;
24
+ const MAX_FETCH_PAIRS = 1000;
25
+ function bytesHex(b) {
26
+ return typeof b === "string" ? b.toLowerCase() : toHex(Uint8Array.from(b));
27
+ }
28
+ /** Every shard at version 0 — the request a first scan sends. */
29
+ export function genesisWatermarks() {
30
+ return Array.from({ length: NUM_PRESHARDS }, (_, i) => [i + 1, 0]);
31
+ }
32
+ function baseUrl(indexerBaseUrl) {
33
+ return indexerBaseUrl.replace(/\/$/, "");
34
+ }
35
+ /** Parses an ndjson UTXO stream body into updates and per-shard resume points. */
36
+ export function parseUtxoStream(body) {
37
+ const out = { unspent: [], spent: [], reached: new Map(), hasMore: false };
38
+ for (const line of body.split("\n")) {
39
+ const trimmed = line.trim();
40
+ if (!trimmed)
41
+ continue;
42
+ const payload = JSON.parse(trimmed);
43
+ if (payload.sos) {
44
+ if (payload.sos.has_more)
45
+ out.hasMore = true;
46
+ out.reached.set(payload.sos.shard, payload.sos.max_state_version);
47
+ }
48
+ const u = payload.update;
49
+ if (u) {
50
+ if ("Unspent" in u)
51
+ out.unspent.push([u.Unspent.tag, bytesHex(u.Unspent.public_nonce)]);
52
+ else if ("Spent" in u)
53
+ out.spent.push(bytesHex(u.Spent.id));
54
+ else if ("Burnt" in u)
55
+ out.spent.push(bytesHex(u.Burnt.id));
56
+ }
57
+ }
58
+ return out;
59
+ }
60
+ async function readStream(indexerBaseUrl, resourceAddress, watermarks, perShardLimit, unspentOnly) {
61
+ const shardStateVersions = watermarks.length > 0 ? watermarks : genesisWatermarks();
62
+ const resp = await fetch(`${baseUrl(indexerBaseUrl)}/utxos/stream`, {
23
63
  method: "POST",
24
- headers: { "Content-Type": "application/json", "Accept": "application/json" },
25
- body: JSON.stringify(body),
64
+ headers: { "Content-Type": "application/json", Accept: "application/x-ndjson" },
65
+ body: JSON.stringify({
66
+ from_epoch: 0,
67
+ resource_address: resourceAddress,
68
+ shard_state_versions: shardStateVersions,
69
+ unspent_only: unspentOnly,
70
+ per_shard_limit: Math.max(1, Math.min(1000, perShardLimit)),
71
+ }),
26
72
  });
27
73
  if (!resp.ok) {
28
74
  const text = await resp.text().catch(() => "");
29
- throw new Error(`UTXO scan POST /${path} failed: ${resp.status} ${resp.statusText} — ${text}`);
75
+ throw new Error(`UTXO scan POST /utxos/stream failed: ${resp.status} ${resp.statusText} — ${text}`);
30
76
  }
31
- return resp.json();
77
+ return parseUtxoStream(await resp.text());
32
78
  }
33
- async function getJson(baseUrl, path, params) {
34
- const qs = new URLSearchParams();
35
- for (const [k, v] of Object.entries(params)) {
36
- if (v !== undefined)
37
- qs.set(k, String(v));
38
- }
39
- const url = baseUrl.replace(/\/$/, "") + "/" + path + "?" + qs.toString();
40
- const resp = await fetch(url, { headers: { "Accept": "application/json" } });
41
- if (!resp.ok) {
42
- const text = await resp.text().catch(() => "");
43
- throw new Error(`UTXO scan GET /${path} failed: ${resp.status} ${resp.statusText} — ${text}`);
79
+ /** Watermarks after a read: every requested shard, advanced to where the read reached. */
80
+ function mergeWatermarks(previous, reached) {
81
+ const base = previous.length > 0 ? previous : genesisWatermarks();
82
+ return base.map(([shard, version]) => {
83
+ const r = reached.get(shard);
84
+ return [shard, r !== undefined && r > version ? r : version];
85
+ });
86
+ }
87
+ /** Full bodies for candidate (tag, nonce) pairs, following `next_cursor`. */
88
+ async function fetchUtxos(indexerBaseUrl, resourceAddress, pairs) {
89
+ const out = [];
90
+ for (let i = 0; i < pairs.length; i += MAX_FETCH_PAIRS) {
91
+ const chunk = pairs.slice(i, i + MAX_FETCH_PAIRS);
92
+ let cursor;
93
+ for (let page = 0; page < 100; page++) {
94
+ const resp = await fetch(`${baseUrl(indexerBaseUrl)}/utxos/fetch`, {
95
+ method: "POST",
96
+ headers: { "Content-Type": "application/json", Accept: "application/json" },
97
+ body: JSON.stringify({ resource_address: resourceAddress, tag_and_nonce_pairs: chunk, ...(cursor ? { cursor } : {}) }),
98
+ });
99
+ if (!resp.ok) {
100
+ const text = await resp.text().catch(() => "");
101
+ throw new Error(`UTXO scan POST /utxos/fetch failed: ${resp.status} ${resp.statusText} — ${text}`);
102
+ }
103
+ const body = (await resp.json());
104
+ for (const [id, utxo] of body.utxos)
105
+ out.push([id, typeof utxo === "string" ? decodeUtxo(utxo) : utxo]);
106
+ if (!body.next_cursor || body.next_cursor === cursor)
107
+ break;
108
+ cursor = body.next_cursor;
109
+ }
44
110
  }
45
- return resp.json();
111
+ return out;
46
112
  }
47
113
  /** Try to decrypt a UTXO output using the account's view key.
48
114
  * Returns a ScannedStealthOutput on success, null if the output doesn't belong to this key. */
@@ -56,115 +122,52 @@ async function tryDecryptUtxo(crypto, viewSecret, resourceAddress, utxoId, utxo)
56
122
  viewSecret,
57
123
  skipMemo: false,
58
124
  });
59
- return {
60
- resourceAddress,
61
- commitment: utxoId,
62
- amount: value,
63
- transactionId: "",
64
- memo,
65
- };
125
+ return { resourceAddress, commitment: utxoId, amount: value, transactionId: "", memo };
66
126
  }
67
127
  catch {
68
128
  return null;
69
129
  }
70
130
  }
131
+ async function decryptCandidates(indexerBaseUrl, resourceAddress, crypto, viewSecret, pairs) {
132
+ const owned = [];
133
+ if (pairs.length === 0)
134
+ return owned;
135
+ for (const [utxoId, utxo] of await fetchUtxos(indexerBaseUrl, resourceAddress, pairs)) {
136
+ const result = await tryDecryptUtxo(crypto, viewSecret, resourceAddress, utxoId, utxo);
137
+ if (result)
138
+ owned.push(result);
139
+ }
140
+ return owned;
141
+ }
71
142
  // ── incremental delta scan ───────────────────────────────────────────────────────────────────────
72
143
  /**
73
- * Fetches all UTXO updates (new outputs + spends) since the given watermarks from the indexer's
74
- * streaming endpoint, then decrypts any `Unspent` candidates with the account's view key.
75
- *
76
- * Pass `watermarks: []` (or the saved value from storage) on every call. The very first call
77
- * with an empty watermarks array replays everything the indexer has retained, so it doubles as the
78
- * initial full scan. Subsequent calls with the returned watermarks fetch only the delta.
79
- *
80
- * Call in a loop until `result.hasMore` is false:
81
- * ```ts
82
- * let wm = await getUtxoScanWatermarks(accountId, resourceAddress);
83
- * do {
84
- * const r = await scanUtxosDelta(indexerUrl, resourceAddress, crypto, viewSecret, wm, 200);
85
- * for (const o of r.owned) await addShieldedOutput({ ...o, accountId, ... });
86
- * for (const c of r.spentCommitments) await markShieldedOutputSpent(accountId, c);
87
- * wm = r.watermarks;
88
- * await setUtxoScanWatermarks(accountId, resourceAddress, wm);
89
- * } while (r.hasMore);
90
- * ```
144
+ * Reads UTXO updates (new outputs + spends) since `watermarks` and decrypts the new outputs with
145
+ * the account's view key. Pass `[]` (or the saved value) on every call; call again with the
146
+ * returned watermarks until `hasMore` is false.
91
147
  */
92
148
  export async function scanUtxosDelta(indexerBaseUrl, resourceAddress, crypto, viewSecret, watermarks, perShardLimit = 200) {
93
- const req = {
94
- resource_address: resourceAddress,
95
- shard_state_versions: watermarks,
96
- unspent_only: false,
97
- per_shard_limit: perShardLimit,
98
- };
99
- const updateSet = await postJson(indexerBaseUrl, "utxos/stream", req);
100
- // Collect spend updates and candidate (tag, nonce) pairs for new outputs
101
- const spentCommitments = [];
102
- const candidates = [];
103
- for (const shardUpdates of Object.values(updateSet.shard_updates)) {
104
- for (const update of shardUpdates.updates) {
105
- if ("Spent" in update) {
106
- spentCommitments.push(update.Spent.id);
107
- }
108
- else if ("Burnt" in update) {
109
- spentCommitments.push(update.Burnt.id);
110
- }
111
- else if ("Unspent" in update) {
112
- candidates.push([update.Unspent.tag, update.Unspent.public_nonce]);
113
- }
114
- }
115
- }
116
- // Batch-fetch full UTXO bodies for all candidates, then decrypt
117
- const owned = [];
118
- if (candidates.length > 0) {
119
- const fetchResp = await postJson(indexerBaseUrl, "utxos/fetch", { resource_address: resourceAddress, tag_and_nonce_pairs: candidates });
120
- for (const [utxoId, utxo] of fetchResp.utxos) {
121
- const result = await tryDecryptUtxo(crypto, viewSecret, resourceAddress, utxoId, utxo);
122
- if (result)
123
- owned.push(result);
124
- }
125
- }
126
- const hasMore = Object.values(updateSet.shard_updates).some((s) => s.has_more);
127
- return {
128
- owned,
129
- spentCommitments,
130
- watermarks: updateSet.per_shard_high_watermark,
131
- hasMore,
132
- };
149
+ const read = await readStream(indexerBaseUrl, resourceAddress, watermarks, perShardLimit, false);
150
+ const owned = await decryptCandidates(indexerBaseUrl, resourceAddress, crypto, viewSecret, read.unspent);
151
+ return { owned, spentCommitments: read.spent, watermarks: mergeWatermarks(watermarks, read.reached), hasMore: read.hasMore };
133
152
  }
134
- // ── full paginated scan ───────────────────────────────────────────────────────────────────────────
153
+ // ── full scan ────────────────────────────────────────────────────────────────────────────────────
135
154
  /**
136
- * Fetches one page of the live UTXO set for a resource and tries to decrypt each output.
137
- *
138
- * Use this when the watermarks are lost or a full re-scan is needed. The `fromId` cursor is the
139
- * `UtxoId` (32-byte commitment hex) of the last output seen on the previous page.
140
- *
141
- * Call in a loop until `result.nextCursor` is null:
142
- * ```ts
143
- * let cursor = await getUtxoScanPageCursor(accountId, resourceAddress);
144
- * do {
145
- * const r = await scanUtxosPage(indexerUrl, resourceAddress, crypto, viewSecret, cursor);
146
- * for (const o of r.owned) await addShieldedOutput({ ...o, accountId, ... });
147
- * cursor = r.nextCursor;
148
- * if (cursor) await setUtxoScanPageCursor(accountId, resourceAddress, cursor);
149
- * } while (cursor !== null);
150
- * await clearUtxoScanPageCursor(accountId, resourceAddress);
151
- * ```
155
+ * One pass of a sweep over every live UTXO of `resourceAddress`. `fromId` is the cursor a previous
156
+ * pass returned (`null` starts a new sweep); a cursor from the pre-0.48 `GET /utxos` API (a bare
157
+ * UtxoId) is ignored and the sweep restarts.
152
158
  */
153
159
  export async function scanUtxosPage(indexerBaseUrl, resourceAddress, crypto, viewSecret, fromId = null, pageSize = 100) {
154
- const resp = await getJson(indexerBaseUrl, "utxos", {
155
- resource_address: resourceAddress,
156
- limit: pageSize,
157
- from_id: fromId ?? undefined,
158
- });
159
- const owned = [];
160
- let lastId = null;
161
- for (const [utxoId, utxo] of resp.utxos) {
162
- lastId = utxoId;
163
- const result = await tryDecryptUtxo(crypto, viewSecret, resourceAddress, utxoId, utxo);
164
- if (result)
165
- owned.push(result);
160
+ let watermarks = [];
161
+ if (fromId && fromId.startsWith("[")) {
162
+ try {
163
+ watermarks = JSON.parse(fromId);
164
+ }
165
+ catch {
166
+ watermarks = [];
167
+ }
166
168
  }
167
- // If the page was full there may be more; if it was shorter than pageSize, we're done
168
- const nextCursor = resp.utxos.length >= pageSize ? lastId : null;
169
- return { owned, nextCursor };
169
+ const read = await readStream(indexerBaseUrl, resourceAddress, watermarks, pageSize, true);
170
+ const owned = await decryptCandidates(indexerBaseUrl, resourceAddress, crypto, viewSecret, read.unspent);
171
+ const next = mergeWatermarks(watermarks, read.reached);
172
+ return { owned, nextCursor: read.hasMore ? JSON.stringify(next) : null };
170
173
  }
package/dist/wallet.d.ts CHANGED
@@ -1033,15 +1033,14 @@ export declare class OotleAccount implements WalletAccountApi {
1033
1033
  * directly, so it finds any output that exists on-chain right now regardless of how old it is or
1034
1034
  * how it was created.
1035
1035
  *
1036
- * **Full paginated mode (default):** Pages through the live UTXO set (`GET /utxos`) ordered by
1037
- * commitment id. Each call reads at most `maxPages` pages and saves its cursor, so a large set
1038
- * is covered across several calls rather than in one unbounded loop; the cursor is cleared once
1039
- * the last page is reached, and the next call starts a fresh sweep.
1036
+ * **Full mode (default):** Sweeps every live UTXO of the resource (`POST /utxos/stream` with
1037
+ * `unspent_only`, from genesis; 0.48 removed `GET /utxos`). Each call reads at most `maxPages`
1038
+ * passes and saves its cursor, so a large set is covered across several calls; the cursor is
1039
+ * cleared once every shard is read, and the next call starts a fresh sweep.
1040
1040
  *
1041
- * **Incremental mode** (`mode: "delta"`): Uses `POST /utxos/stream` with saved shard watermarks.
1042
- * Not the default: against the Esmeralda indexer on 2026-10-27 it returned an empty body for an
1043
- * empty-watermark request (observed only; the endpoint's intended semantics are unverified).
1044
- * Spent updates from it are recorded as *inferred* spends, which a later sighting can undo.
1041
+ * **Incremental mode** (`mode: "delta"`): `POST /utxos/stream` from saved shard watermarks,
1042
+ * including spends. Spent updates are recorded as *inferred* spends, which a later sighting can
1043
+ * undo.
1045
1044
  *
1046
1045
  * Any owned output seen in the live set that a local record had marked spent only on an
1047
1046
  * indexer's say-so is revived (see `reviveShieldedOutput`).