@chironbuilder/ootle-sdk 0.1.29 → 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 (35) 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/index.d.ts +1 -1
  5. package/dist/index.d.ts.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/indexerDecode.d.ts +23 -0
  8. package/dist/indexerDecode.d.ts.map +1 -0
  9. package/dist/indexerDecode.js +68 -0
  10. package/dist/storage.d.ts +11 -0
  11. package/dist/storage.d.ts.map +1 -1
  12. package/dist/utxoScan.d.ts +24 -39
  13. package/dist/utxoScan.d.ts.map +1 -1
  14. package/dist/utxoScan.js +136 -133
  15. package/dist/wallet.d.ts +28 -8
  16. package/dist/wallet.d.ts.map +1 -1
  17. package/dist/wallet.js +166 -82
  18. package/package.json +8 -8
  19. package/vendor/ootle-wasm-patched/chiron-0.49.2.patch +199 -0
  20. package/vendor/ootle-wasm-patched/ootle_wasm.d.ts +53 -35
  21. package/vendor/ootle-wasm-patched/ootle_wasm.js +1 -1
  22. package/vendor/ootle-wasm-patched/ootle_wasm_bg.js +158 -45
  23. package/vendor/ootle-wasm-patched/ootle_wasm_bg.wasm +0 -0
  24. package/vendor/ootle-wasm-patched/ootle_wasm_bg.wasm.d.ts +15 -12
  25. package/vendor/ootle-wasm-patched/package.json +3 -3
  26. package/vendor/ootle-patched/README.md +0 -67
  27. package/vendor/ootle-patched/dist/index.d.ts +0 -2158
  28. package/vendor/ootle-patched/dist/index.js +0 -1389
  29. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/README.md +0 -128
  30. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/ootle_wasm.d.ts +0 -436
  31. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/ootle_wasm.js +0 -9
  32. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/ootle_wasm_bg.js +0 -1450
  33. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/ootle_wasm_bg.wasm +0 -0
  34. package/vendor/ootle-patched/node_modules/@tari-project/ootle-wasm/package.json +0 -30
  35. package/vendor/ootle-patched/package.json +0 -23
@@ -1,2158 +0,0 @@
1
- import { AllocatableAddressType } from '@tari-project/ootle-ts-bindings';
2
- import { Amount } from '@tari-project/ootle-ts-bindings';
3
- import { ClaimBurnOutputData } from '@tari-project/ootle-ts-bindings';
4
- import { ClaimedOutputTombstoneAddress } from '@tari-project/ootle-ts-bindings';
5
- import { ComponentAddress } from '@tari-project/ootle-ts-bindings';
6
- import { ConfidentialWithdrawProof } from '@tari-project/ootle-ts-bindings';
7
- import { Decision } from '@tari-project/ootle-ts-bindings';
8
- import { ExecuteResult } from '@tari-project/ootle-ts-bindings';
9
- import { FinalizeOutcome } from '@tari-project/ootle-ts-bindings';
10
- import { FinalizeResult } from '@tari-project/ootle-ts-bindings';
11
- import { GetSubstatesRequest } from '@tari-project/ootle-ts-bindings';
12
- import { GetSubstatesResponse } from '@tari-project/ootle-ts-bindings';
13
- import { GetTemplateDefinitionResponse } from '@tari-project/ootle-ts-bindings';
14
- import { IndexerGetSubstateRequest } from '@tari-project/ootle-ts-bindings';
15
- import { IndexerGetSubstateResponse } from '@tari-project/ootle-ts-bindings';
16
- import { IndexerGetTransactionResultResponse } from '@tari-project/ootle-ts-bindings';
17
- import { IndexerSubmitTransactionRequest } from '@tari-project/ootle-ts-bindings';
18
- import { IndexerSubmitTransactionResponse } from '@tari-project/ootle-ts-bindings';
19
- import { IndexerTransactionFinalizedResult } from '@tari-project/ootle-ts-bindings';
20
- import { InputDeclaration } from '@tari-project/ootle-ts-bindings';
21
- import { Instruction } from '@tari-project/ootle-ts-bindings';
22
- import { InstructionArg } from '@tari-project/ootle-ts-bindings';
23
- import { ListRecentTransactionsRequest } from '@tari-project/ootle-ts-bindings';
24
- import { ListRecentTransactionsResponse } from '@tari-project/ootle-ts-bindings';
25
- import { MinotariBurnClaimProof } from '@tari-project/ootle-ts-bindings';
26
- import { NonFungibleAddress } from '@tari-project/ootle-ts-bindings';
27
- import { OutputBody } from '@tari-project/ootle-ts-bindings';
28
- import { PublishedTemplateAddress } from '@tari-project/ootle-ts-bindings';
29
- import { RejectReason } from '@tari-project/ootle-ts-bindings';
30
- import { ResourceAddress } from '@tari-project/ootle-ts-bindings';
31
- import { RistrettoPublicKeyBytes } from '@tari-project/ootle-ts-bindings';
32
- import { StealthTransferStatement as StealthTransferStatement_2 } from '@tari-project/ootle-ts-bindings';
33
- import { SubstateId } from '@tari-project/ootle-ts-bindings';
34
- import { SubstateRequirement } from '@tari-project/ootle-ts-bindings';
35
- import { Transaction } from '@tari-project/ootle-ts-bindings';
36
- import { TransactionEnvelope } from '@tari-project/ootle-ts-bindings';
37
- import { TransactionSignature } from '@tari-project/ootle-ts-bindings';
38
- import { TransactionV1 } from '@tari-project/ootle-ts-bindings';
39
- import { UnsealedTransactionV1 } from '@tari-project/ootle-ts-bindings';
40
- import { UnsignedTransactionV1 } from '@tari-project/ootle-ts-bindings';
41
- import { UtxoAddress } from '@tari-project/ootle-ts-bindings';
42
- import { ValidatorFeePoolAddress } from '@tari-project/ootle-ts-bindings';
43
- import { VaultId } from '@tari-project/ootle-ts-bindings';
44
- import { WorkspaceOffsetId } from '@tari-project/ootle-ts-bindings';
45
-
46
- /**
47
- * Fluent builder for common account component invocations.
48
- * Mirrors `AccountInvokeBuilder` from the Rust ootle-rs crate.
49
- *
50
- * @example
51
- * ```ts
52
- * const tx = new AccountInvokeBuilder(network, maxEpoch)
53
- * .feeTransactionPayFromComponent(accountAddress, 1000n)
54
- * .publicTransfer(accountAddress, resourceAddress, 500n, recipientAddress)
55
- * .build();
56
- * ```
57
- */
58
- export declare class AccountInvokeBuilder {
59
- private builder;
60
- constructor(network: Network | number, maxEpoch: number);
61
- /**
62
- * Declares the transaction's substate inputs (e.g. the source account and its
63
- * vaults) so the indexer resolves their versions before submission.
64
- */
65
- withInputs(inputs: SubstateRequirement[]): this;
66
- /**
67
- * Adds a fee instruction paying from the account's default vault.
68
- */
69
- feeTransactionPayFromComponent(componentAddress: ComponentAddress, maxFee: bigint): this;
70
- /**
71
- * Transfers `amount` of `resource` from `sourceAccount` to `destinationAddress`.
72
- * Mirrors `AccountInvokeBuilder::public_transfer` from ootle-rs.
73
- */
74
- publicTransfer(sourceAccount: ComponentAddress, resourceAddress: ResourceAddress, amount: bigint, destinationAddress: string): this;
75
- /**
76
- * Publishes a compiled template WASM blob (standard-base64 encoded).
77
- * Mirrors `AccountInvokeBuilder::publish_template` from ootle-rs.
78
- *
79
- * `sourceAccount` is the fee payer; declare it via {@link feeTransactionPayFromComponent}
80
- * and {@link withInputs}. Pass `workspaceBucket` to capture the new template address
81
- * for a follow-up instruction.
82
- */
83
- publishTemplate(_sourceAccount: ComponentAddress, templateBinaryBase64: string, workspaceBucket?: string): this;
84
- build(): UnsignedTransactionV1;
85
- }
86
-
87
- export { Amount }
88
-
89
- /**
90
- * CBOR-encode an `Amount` (u128) the way the runtime's `minicbor` codec does:
91
- * a plain CBOR unsigned integer while the value fits the CBOR integer range
92
- * (`0..=u64::MAX`), and an RFC 8949 tag-2 unsigned bignum (minimal-length
93
- * big-endian byte string) above it.
94
- *
95
- * Wire-breaking against the pre-0.39 `[lo_u64, hi_u64]` digit-array form —
96
- * templates built against an older `tari_template_lib` cannot decode this.
97
- *
98
- * @throws {InvalidArgumentError} if `value` is negative or overflows u128.
99
- */
100
- export declare function amountLiteral(value: bigint): InstructionArg;
101
-
102
- /**
103
- * Asserts that `bytes` has exactly `length` bytes; otherwise throws with a
104
- * descriptive message. Returns `bytes` so the assertion can be used inline in a
105
- * property initialiser or destructuring expression.
106
- *
107
- * Message format deliberately mirrors the existing stealth-side inline checks
108
- * (e.g. `Mask must be 32 bytes, got 31`).
109
- *
110
- * @throws {InvalidArgumentError} when the length does not match.
111
- */
112
- export declare function assertByteLength(bytes: Uint8Array, length: number, name: string): Uint8Array;
113
-
114
- /**
115
- * Standard TypeScript exhaustiveness helper. Use at the bottom of a `switch` over
116
- * a discriminated union (or any branch the type system has narrowed to `never`)
117
- * to assert at compile-time that every case is handled — and throw at runtime if
118
- * an unhandled value sneaks past the type checker.
119
- */
120
- export declare function assertUnreachable(x: never, hint?: string): never;
121
-
122
- /**
123
- * The post-{@link WalletStealthAuthorizer.prepare} handle.
124
- *
125
- * Owns the hydrated spec, the resolved stealth inputs, and the single seal keypair shared
126
- * across one-time authorizations and the seal signature. Constructed only via
127
- * {@link WalletStealthAuthorizer.prepare} — there is no way to obtain one without preparing
128
- * first, so {@link seal} / {@link createAuthorizations} no longer need a `prepared` guard.
129
- */
130
- export declare class AuthorizedTransfer {
131
- private readonly wallet;
132
- private readonly crypto;
133
- private readonly spec;
134
- private readonly resolvedInputs;
135
- private readonly mustSignWithAccountKey;
136
- /**
137
- * The single seal keypair, generated once and shared across the one-time spend-key
138
- * authorizations (which hash the tx with its public key) and the final {@link seal}. Every
139
- * signature must be over the same tx hash, which depends on this exact seal public key.
140
- */
141
- private readonly sealKeypair;
142
- /** Extra signatures appended via {@link addSignature} before sealing. */
143
- private readonly extraSignatures;
144
- /**
145
- * Memoized one-time spend-key authorizations — see {@link createAuthorizations} for the
146
- * lifecycle and why memoization (not recomputation) is required.
147
- */
148
- private cachedAuthorizations?;
149
- constructor(params: AuthorizedTransferParams);
150
- /** The shared seal signer public key (fixed for this transfer's lifetime). */
151
- getSealPublicKey(): Uint8Array;
152
- /** The hydrated, post-`prepare` spec (balance proof filled, instruction patched). */
153
- getSpec(): StealthTransferSpec;
154
- /**
155
- * Produce the one-time spend-key authorizations for the stealth inputs (empty for a
156
- * revealed-only transfer).
157
- *
158
- * For each resolved input, picks the owner's signer from the wallet and calls its
159
- * `addStealthSignature(unsignedJson, publicNonce, sealPublicKey, { crypto })` — which
160
- * derives the one-time spend scalar via `stealthDhSecret` and signs the tx hash. The
161
- * secret stays in the signer (never pulled into the transfer).
162
- *
163
- * Uses this transfer's shared seal public key ({@link getSealPublicKey}) — the same one
164
- * {@link seal} uses — so every signature is over the same tx hash. The tx hashed is
165
- * `spec.unsignedTx` (already resolved by the builder); {@link seal} does not re-resolve,
166
- * so the hashes match.
167
- *
168
- * **Memoized.** The authorizations are computed on the first call and cached; every
169
- * subsequent call — including the internal one from {@link seal} — returns the *same*
170
- * array, never re-signing with a fresh random nonce. Calling this before {@link seal}
171
- * cannot double-count, because {@link seal} reuses the cache. Callers therefore must
172
- * **not** feed these one-time authorizations to {@link addSignature} — they are
173
- * auto-included exactly once at seal time.
174
- *
175
- * @throws {KeyProviderNotFoundError} if a stealth-input owner has no signer registered.
176
- * @throws {SignerError} if a stealth-input owner's signer cannot produce one-time
177
- * stealth signatures (lacks `addStealthSignature`).
178
- */
179
- createAuthorizations(): Promise<TransactionAuthorization[]>;
180
- /**
181
- * Sign each resolved stealth input with its owner's one-time spend key (fresh random
182
- * nonce per signature). Called **once** via {@link createAuthorizations}'s memoization —
183
- * never directly — so the random-nonce signatures are produced a single time.
184
- */
185
- private computeAuthorizations;
186
- /**
187
- * Append an extra signature for a **genuine external co-signer** to be included when
188
- * sealing. The account-key signature is added automatically at {@link seal} unless
189
- * `mustSignWithAccountKey` is `false`.
190
- *
191
- * Do **NOT** pass the per-input one-time spend-key authorizations here — they are
192
- * produced (memoized) by {@link createAuthorizations} and auto-included by {@link seal}
193
- * exactly once. Re-adding them via this method would double-count them in the sealed tx,
194
- * which the engine rejects.
195
- */
196
- addSignature(signature: TransactionSignature): this;
197
- /**
198
- * Sign and seal the (prepared) transfer into a `TransactionEnvelope`.
199
- *
200
- * Composes, over a SINGLE shared seal keypair:
201
- * - the account-key signature (unless `mustSignWithAccountKey` is `false`);
202
- * - the per-input **one-time spend-key authorizations** — included **exactly once** per
203
- * stealth input via {@link createAuthorizations}'s memoized cache, whether or not the
204
- * caller invoked {@link createAuthorizations} first; callers must NOT also re-add them
205
- * via {@link addSignature};
206
- * - any {@link addSignature} extras (e.g. genuine external co-signers).
207
- *
208
- * All of these — and the seal signature itself — hash the tx with the same seal public
209
- * key, so every signature verifies against the same hash. The tx is **not** re-resolved
210
- * here (the builder already resolved it in `prepare()`); re-resolving could change the
211
- * hash and invalidate the already-computed one-time authorizations.
212
- *
213
- * @throws {KeyProviderNotFoundError} when a stealth-input owner has no signer registered.
214
- * @throws {SignerError} when a stealth-input signer cannot produce one-time signatures.
215
- */
216
- seal(): Promise<TransactionEnvelope>;
217
- }
218
-
219
- /**
220
- * Parameters for the {@link AuthorizedTransfer} constructor. Kept internal — the only
221
- * construction path is via {@link WalletStealthAuthorizer.prepare}.
222
- */
223
- declare interface AuthorizedTransferParams {
224
- wallet: OotleWallet;
225
- crypto: StealthCryptoProvider;
226
- spec: StealthTransferSpec;
227
- resolvedInputs: ResolvedStealthInput[];
228
- mustSignWithAccountKey: boolean;
229
- sealKeypair: SealKeypair;
230
- }
231
-
232
- /**
233
- * The balance-proof Schnorr signature `(public_nonce, signature)`. For a
234
- * fully-revealed transfer this pair is normally omitted on the envelope.
235
- */
236
- export declare class BalanceProofSignature {
237
- private readonly _publicNonce;
238
- private readonly _signature;
239
- constructor(publicNonce: Uint8Array, signature: Uint8Array);
240
- /** 32-byte public nonce (defensive copy). */
241
- get publicNonce(): Uint8Array;
242
- /** 32-byte signature scalar (defensive copy). */
243
- get signature(): Uint8Array;
244
- toJSON(): BalanceProofSignatureJson;
245
- static fromJSON(json: BalanceProofSignatureJson): BalanceProofSignature;
246
- }
247
-
248
- /** Wire shape of a {@link BalanceProofSignature}. */
249
- declare interface BalanceProofSignatureJson {
250
- public_nonce: string;
251
- signature: string;
252
- }
253
-
254
- /** CBOR-encode a `bool` as a CBOR boolean primitive. */
255
- export declare function boolLiteral(value: boolean): InstructionArg;
256
-
257
- /**
258
- * Assemble a TransactionSignature from a 32-byte public key and a Schnorr
259
- * `(public_nonce, signature)` pair. Asserts the 32-byte length on all three
260
- * inputs at the trust boundary so length regressions surface here, not deeper.
261
- */
262
- export declare function buildTransactionSignature(publicKey: Uint8Array, sig: {
263
- public_nonce: Uint8Array;
264
- signature: Uint8Array;
265
- }): TransactionSignature;
266
-
267
- /**
268
- * Internal base for 32-byte stealth-domain carriers (`Mask`, `StealthInput`).
269
- * Asserts the 32-byte length at construction and defensively copies on the way
270
- * in; subclasses inherit `toBytes()` / `toHex()` which return fresh copies.
271
- *
272
- * Exported for cross-file extension by `StealthInput` in `./statements`; not
273
- * part of the public package surface (not re-exported from `./types`).
274
- */
275
- declare abstract class Bytes32 {
276
- private readonly bytes;
277
- protected constructor(bytes: Uint8Array, fieldName: string);
278
- toBytes(): Uint8Array;
279
- toHex(): string;
280
- }
281
-
282
- /** CBOR-encode a `Vec<u8>` as a CBOR byte string. */
283
- export declare function bytesLiteral(value: Uint8Array): InstructionArg;
284
-
285
- /**
286
- * CBOR-encode a `ClaimedOutputTombstoneAddress` as `Tag(136, bytes(32))`.
287
- * Accepts either the `tombstone_<hex>` form or the bare 64-hex-char tail.
288
- *
289
- * @throws {InvalidArgumentError} if the address body is not 32 bytes (64 hex chars).
290
- */
291
- export declare function claimedOutputTombstoneAddressLiteral(address: ClaimedOutputTombstoneAddress): InstructionArg;
292
-
293
- /**
294
- * @throws {InvalidArgumentError} if `result` carries an unrecognised `final_decision`
295
- * variant (an indexer protocol mismatch — defence-in-depth).
296
- */
297
- export declare function classifyOutcome(result: IndexerTransactionFinalizedResult): {
298
- outcome: FinalizeOutcome | "Reject";
299
- reason?: string;
300
- } | null;
301
-
302
- /**
303
- * Extract the 32-byte commitment from a UTXO substate id.
304
- *
305
- * A UTXO id has the form `utxo_{resourceHex}_{commitmentHex}`; the commitment is the
306
- * **trailing** hex segment. Returns `null` if the id is not a UTXO id (wrong prefix,
307
- * e.g. a component/vault id) or the trailing segment is not exactly 32 bytes of hex.
308
- *
309
- * The commitment is **never** in the output body — always derive it from the id.
310
- *
311
- * @param substateId - The full substate id string.
312
- * @returns The 32-byte commitment, or `null` if `substateId` is not a valid UTXO id.
313
- */
314
- export declare function commitmentOf(substateId: string): Uint8Array | null;
315
-
316
- /**
317
- * The only outcome a `PendingTransaction.watch()` can resolve to: a successful
318
- * commit. Every non-commit verdict (Reject, FeeIntentCommit, timeout, cancel)
319
- * throws instead, so the return type is narrowed to this rather than the full
320
- * {@link TransactionOutcome} union.
321
- */
322
- export declare interface CommitOutcome {
323
- outcome: "Commit";
324
- }
325
-
326
- /**
327
- * CBOR-encode a `ComponentAddress` as `Tag(128, bytes(32))`. Accepts either the
328
- * `component_<hex>` form or the bare 64-hex-char tail.
329
- *
330
- * @throws {InvalidArgumentError} if the address body is not 32 bytes (64 hex chars).
331
- */
332
- export declare function componentAddressLiteral(address: ComponentAddress): InstructionArg;
333
-
334
- /**
335
- * Construct an {@link Output}, applying the conventional defaults and validating
336
- * the amount.
337
- *
338
- * @throws {InvalidArgumentError} if `amount <= 0n`.
339
- */
340
- export declare function createOutput(init: OutputInit): Output;
341
-
342
- /**
343
- * Raised when the WASM crypto bridge fails (AEAD decryption, balance-proof
344
- * verification, scalar parsing, …). `context` is a short label identifying which
345
- * bridge call failed; the original bridge error chains via `cause`.
346
- */
347
- export declare class CryptoBridgeError extends OotleError {
348
- readonly context?: string;
349
- constructor(message: string, options?: ErrorOptions & {
350
- context?: string;
351
- });
352
- }
353
-
354
- export { Decision }
355
-
356
- /**
357
- * The result of decrypting an owned output via the AEAD path (`unblindOutput`).
358
- *
359
- * Maps from the WASM `DecryptedOutputResult { mask: Uint8Array, value: bigint,
360
- * memo_json: string | undefined }`. Per the verified 0.38 ABI, `memo` is the
361
- * **JSON-encoded `Memo` string** (`U256` / `Message` / `Bytes` / `PayRefAndBytes`),
362
- * not raw bytes — callers parse it if needed.
363
- */
364
- export declare interface DecryptedData {
365
- /** Recovered output blinding factor. */
366
- mask: Mask;
367
- /** Recovered µTari amount. */
368
- value: bigint;
369
- /** The JSON-encoded `Memo` string, if present. */
370
- memo?: string;
371
- }
372
-
373
- /**
374
- * Decrypt an output's encrypted data given its raw commitment + ciphertext bytes.
375
- *
376
- * Derives the AEAD key (`deriveAeadKey(viewSecret, senderPublicNonce)`) and unblinds.
377
- * **Throws** (via `unblindOutput`) when the output is not owned — callers that scan a
378
- * batch should prefer {@link decryptOwnedUtxo}, which swallows that throw.
379
- *
380
- * @param crypto - The crypto seam (real WASM or a fake).
381
- * @param commitment - The output's 32-byte Pedersen commitment.
382
- * @param encryptedData - The raw ciphertext bytes.
383
- * @param options - The sender public nonce, recipient view secret, and `skipMemo` flag.
384
- * @returns The decrypted value / mask / memo.
385
- */
386
- export declare function decryptInputData(crypto: StealthCryptoProvider, commitment: Uint8Array, encryptedData: Uint8Array, options: DecryptInputOptions): Promise<DecryptedData>;
387
-
388
- /** Inputs to {@link decryptInputData}. All byte fields are raw `Uint8Array`. */
389
- export declare interface DecryptInputOptions {
390
- /** The output's sender public nonce (the substate body `public_nonce`, as bytes). */
391
- senderPublicNonce: Uint8Array;
392
- /** The recipient's 32-byte view secret. */
393
- viewSecret: Uint8Array;
394
- /** When `true`, the memo is not decrypted. */
395
- skipMemo: boolean;
396
- }
397
-
398
- /**
399
- * The recipient owner-read: try to decrypt a fetched UTXO substate with a view secret.
400
- *
401
- * Parses the substate (commitment from the id, `public_nonce` + `encrypted_data` from
402
- * the body), derives the AEAD key, and unblinds. Returns the {@link DecryptedData} for
403
- * an owned UTXO, or `null` when the substate is not a live stealth UTXO **or** the
404
- * decrypt throws (the "not ours" signal). This lets a recipient scan many substates in
405
- * a loop without a try/catch at each call site.
406
- *
407
- * @param crypto - The crypto seam (real WASM or a fake).
408
- * @param viewSecret - The recipient's 32-byte view secret.
409
- * @param substate - The fetched substate response.
410
- * @param substateId - The substate id the response was fetched by (source of the commitment).
411
- * @returns The decrypted output if owned, else `null`.
412
- */
413
- export declare function decryptOwnedUtxo(crypto: StealthCryptoProvider, viewSecret: Uint8Array, substate: IndexerGetSubstateResponse, substateId: string): Promise<DecryptedData | null>;
414
-
415
- /**
416
- * The validity window {@link resolveMaxEpoch} applies when the caller does not name one.
417
- * Ten epochs is comfortably longer than a transaction takes to finalize while still
418
- * letting a stuck transaction die on its own rather than lingering as a resubmittable
419
- * intent.
420
- */
421
- export declare const DEFAULT_TRANSACTION_VALIDITY_EPOCHS = 10;
422
-
423
- /**
424
- * Returns a known default indexer URL for the given network.
425
- * Mirrors `default_indexer_url()` from the Rust ootle-rs crate.
426
- *
427
- * @throws {InvalidArgumentError} for networks where no default URL is configured.
428
- */
429
- export declare function defaultIndexerUrl(network: Network): string;
430
-
431
- /** The wallet has no default signer to sign / seal with. */
432
- export declare class DefaultSignerNotSetError extends WalletError {
433
- }
434
-
435
- /**
436
- * Opaque carrier for an output's ciphertext bytes (the AEAD-encrypted value/mask/memo
437
- * payload). Treated as opaque here: the stealth module never inspects the plaintext
438
- * structure, only carries the bytes across the JSON boundary.
439
- */
440
- export declare class EncryptedData {
441
- private readonly bytes;
442
- constructor(bytes: Uint8Array);
443
- /** Parse a hex string into `EncryptedData` (variable length). */
444
- static fromHex(hex: string): EncryptedData;
445
- /** Raw ciphertext bytes (defensive copy). */
446
- toBytes(): Uint8Array;
447
- /** Hex encoding. */
448
- toHex(): string;
449
- }
450
-
451
- export { ExecuteResult }
452
-
453
- /**
454
- * Fluent builder for common faucet component invocations.
455
- * Mirrors `FaucetInvokeBuilder` from the Rust ootle-rs crate.
456
- *
457
- * @example
458
- * ```ts
459
- * const tx = new FaucetInvokeBuilder(network, maxEpoch, faucetAddress)
460
- * .feeTransactionPayFromComponent(accountAddress, 1000n)
461
- * .takeFaucetFunds(accountAddress, 10_000n)
462
- * .build();
463
- * ```
464
- */
465
- export declare class FaucetInvokeBuilder {
466
- private builder;
467
- private readonly faucetAddress;
468
- constructor(network: Network | number, maxEpoch: number, faucetAddress: ComponentAddress);
469
- feeTransactionPayFromComponent(componentAddress: ComponentAddress, maxFee: bigint): this;
470
- /**
471
- * Takes `amount` of funds from the faucet and deposits them into `destinationAccount`.
472
- * Mirrors `FaucetInvokeBuilder::take_faucet_funds` from ootle-rs.
473
- */
474
- takeFaucetFunds(destinationAccount: ComponentAddress, amount: bigint): this;
475
- /**
476
- * Takes the maximum available funds from the faucet into `destinationAccount`.
477
- * Mirrors `FaucetInvokeBuilder::take_max_faucet_funds` from ootle-rs.
478
- */
479
- takeMaxFaucetFunds(destinationAccount: ComponentAddress): this;
480
- /**
481
- * Publishes a template from the faucet component address.
482
- * Mirrors `FaucetInvokeBuilder::publish_template` from ootle-rs.
483
- */
484
- publishTemplate(templateAddress: PublishedTemplateAddress, workspaceBucket?: string): this;
485
- build(): UnsignedTransactionV1;
486
- }
487
-
488
- export { FinalizeOutcome }
489
-
490
- export { FinalizeResult }
491
-
492
- /**
493
- * Decodes a hex string into bytes.
494
- *
495
- * Strict: rejects odd-length input and any character outside `[0-9a-fA-F]`.
496
- * Returns an empty `Uint8Array` for an empty input.
497
- *
498
- * @throws {InvalidArgumentError} if `hex` has odd length or contains non-hex characters.
499
- */
500
- export declare function fromHexStr(hex: string): Uint8Array;
501
-
502
- /**
503
- * Faucet / public-stealth convenience: build a **complete** {@link StealthTransferStatement}
504
- * for a transfer that has no stealth inputs (e.g. a faucet minting confidential outputs, or
505
- * any revealed → stealth transfer that doesn't need the full {@link StealthTransfer} builder).
506
- *
507
- * Generates the outputs statement, uses a zero (`Mask.zero()`) input mask over an empty
508
- * revealed-only inputs statement, signs the balance proof, and returns a ready-to-embed
509
- * statement (`balanceProof` filled). The output mask is non-zero (there is ≥1 stealth
510
- * output), so the proof is real — not the omitted all-zeros case.
511
- *
512
- * For multi-step transfers with revealed change / fee, prefer the {@link StealthTransfer}
513
- * builder + {@link WalletStealthAuthorizer}; this is the one-shot helper.
514
- *
515
- * @param crypto - The crypto seam (real WASM or a fake).
516
- * @param specs - The stealth outputs to create (must be non-empty).
517
- * @param revealed - The revealed (un-confidential) output amount (0 for fully-stealth).
518
- * @returns A complete transfer statement.
519
- * @throws {InvalidArgumentError} if `specs` is empty.
520
- */
521
- export declare function generateOutputsStatement(crypto: StealthCryptoProvider, specs: Output[], revealed: bigint, revealedReceiver?: Uint8Array): Promise<StealthTransferStatement>;
522
-
523
- /**
524
- * Generate a fresh seal keypair (a thin wrapper over the WASM `generateKeypair`).
525
- *
526
- * Exposed so a caller that needs the seal **public key before sealing** can fix the
527
- * keypair once and thread the same public key through other signatures that hash with
528
- * it (the stealth one-time authorizations — see {@link signTransaction}'s `sealKeypair`
529
- * parameter). Keeps `@tari-project/ootle-wasm` out of the `stealth/` module.
530
- */
531
- export declare function generateSealKeypair(): SealKeypair;
532
-
533
- export { GetSubstatesRequest }
534
-
535
- export { GetSubstatesResponse }
536
-
537
- export { GetTemplateDefinitionResponse }
538
-
539
- /**
540
- * Fetch `account` and return the list of vault ids it references (depth-first,
541
- * unique). Returns an empty array if the component does not exist or holds no
542
- * vaults.
543
- */
544
- export declare function getVaultIdsForAccount(provider: Provider, account: ComponentAddress): Promise<string[]>;
545
-
546
- /**
547
- * Raised when the indexer transport fails or returns a non-success response.
548
- *
549
- * `status` is the HTTP status if the request reached the indexer (else `undefined`,
550
- * e.g. a connection-layer failure). `body` is the raw response body when
551
- * available, and `url` is the request URL. The original transport error chains via
552
- * `cause`.
553
- */
554
- export declare class IndexerClientError extends OotleError {
555
- readonly status?: number;
556
- readonly body?: string;
557
- readonly url?: string;
558
- constructor(message: string, options?: ErrorOptions & {
559
- status?: number;
560
- body?: string;
561
- url?: string;
562
- });
563
- }
564
-
565
- export { IndexerGetSubstateRequest }
566
-
567
- export { IndexerGetSubstateResponse }
568
-
569
- export { IndexerGetTransactionResultResponse }
570
-
571
- export { IndexerSubmitTransactionRequest }
572
-
573
- export { IndexerSubmitTransactionResponse }
574
-
575
- export { IndexerTransactionFinalizedResult }
576
-
577
- export { Instruction }
578
-
579
- export { InstructionArg }
580
-
581
- /**
582
- * CBOR-encode a plain integer (Rust `u8`…`u128` / `i8`…`i128`) as a bare CBOR
583
- * integer. Distinct from {@link amountLiteral} only above the CBOR integer
584
- * range, where an `Amount` becomes a tag-2 bignum and this throws instead.
585
- *
586
- * @throws {InvalidArgumentError} if the magnitude exceeds the 64-bit CBOR
587
- * integer range (128-bit bignum encoding is not supported).
588
- */
589
- export declare function intLiteral(value: bigint): InstructionArg;
590
-
591
- /** Raised when builder / helper inputs fail TS-side validation or state-machine checks. */
592
- export declare class InvalidArgumentError extends OotleError {
593
- }
594
-
595
- /**
596
- * Type guard for the native `StealthTransfer` {@link Instruction} variant. Used by the
597
- * authorizer to locate the single stealth instruction it must patch.
598
- */
599
- export declare function isStealthTransferInstruction(instruction: Instruction): instruction is StealthTransferInstruction;
600
-
601
- /**
602
- * Walk the JSON-rendered `tari_bor::Value` of a component's state and yield every
603
- * 32-byte payload of a `Tag(VAULT_ID, Bytes(..))` node — i.e. every vault id the
604
- * component references. Depth-first, unique by hex payload.
605
- *
606
- * The engine emits values that don't map cleanly to JSON via a `{"@cbor": …}`
607
- * sentinel object; this walker handles `tag`, `map`, and `bytes` sentinels and
608
- * recurses through plain text-keyed maps and arrays.
609
- */
610
- export declare function iterVaultIdsInState(value: unknown): Generator<string>;
611
-
612
- /**
613
- * The wallet has no signer registered for the given address.
614
- *
615
- * `address` is intentionally typed as `unknown`: the wallet may register key
616
- * providers under any keying shape (a `ComponentAddress`, a `ResourceAddress`, …),
617
- * and the typed error should not pollute the consumer's downstream signature.
618
- */
619
- export declare class KeyProviderNotFoundError extends WalletError {
620
- readonly address: unknown;
621
- constructor(message: string, options: ErrorOptions & {
622
- address: unknown;
623
- });
624
- }
625
-
626
- /**
627
- * CBOR-encode a value into an `InstructionArg::Literal` by its JavaScript type:
628
- * `bigint` → `Amount`, `string` → CBOR text, `boolean` → CBOR bool,
629
- * `Uint8Array` → CBOR byte string. For tagged on-chain addresses use
630
- * {@link resourceAddressLiteral} / {@link componentAddressLiteral} instead — a
631
- * raw address string would be encoded as plain text, not a tagged object key.
632
- *
633
- * @throws {InvalidArgumentError} if `value` is not one of the supported types.
634
- */
635
- export declare function literalArg(value: bigint | string | boolean | Uint8Array): InstructionArg;
636
-
637
- /**
638
- * A 32-byte blinding factor (Pedersen-commitment mask).
639
- *
640
- * Use {@link Mask.zero} for the faucet / revealed-only path (an all-zero scalar).
641
- */
642
- export declare class Mask extends Bytes32 {
643
- constructor(bytes: Uint8Array);
644
- /** All-zero 32-byte mask, for the faucet / revealed-only path. */
645
- static zero(): Mask;
646
- /** Wrap raw 32 bytes into a `Mask` (validates length, defensive copy in the ctor). */
647
- static fromBytes(bytes: Uint8Array): Mask;
648
- /** Parse a 64-char hex string into a `Mask` (validates length). */
649
- static fromHex(hex: string): Mask;
650
- }
651
-
652
- /**
653
- * The longest validity window any network accepts, in epochs
654
- * (`ConsensusConstants::max_transaction_validity_epochs`, ~30 days). A transaction whose
655
- * `max_epoch` sits further ahead of the current epoch than this is aborted with
656
- * `AbortReason::ValidityWindowTooLong`.
657
- */
658
- export declare const MAX_TRANSACTION_VALIDITY_EPOCHS = 2160;
659
-
660
- /**
661
- * CBOR-encode a `Metadata` map as `Tag(129, Map<text, text>)`. Keys are emitted
662
- * sorted to match the runtime's `BTreeMap` ordering.
663
- */
664
- export declare function metadataLiteral(entries: Record<string, string> | Map<string, string>): InstructionArg;
665
-
666
- /**
667
- * Encodes a µTari amount as a BOR-CBOR-encoded hex `Literal` instruction argument.
668
- *
669
- * Delegates to {@link amountLiteral}: the runtime's `InstructionArg::Literal` carries
670
- * a hex string whose bytes are a `tari_bor::encode(value)` CBOR payload, **not** the
671
- * decimal-string form. Keeping the public type as `bigint` preserves precision for
672
- * values above `Number.MAX_SAFE_INTEGER`.
673
- *
674
- * @throws {InvalidArgumentError} if `amount` is negative or overflows u128.
675
- */
676
- export declare function microTariLiteral(amount: bigint): InstructionArg;
677
-
678
- /**
679
- * Canonical µTari → decimal-string encoding used wherever the bindings expect a
680
- * string-encoded amount on the wire (e.g. structural `toJSON()` views of stealth
681
- * statements). **Not** the BOR-CBOR `Literal` form — use {@link microTariLiteral}
682
- * / {@link amountLiteral} for instruction arguments.
683
- *
684
- * @throws {InvalidArgumentError} if `amount` is negative.
685
- */
686
- export declare function microTariString(amount: bigint): string;
687
-
688
- /**
689
- * A NamedArg is either:
690
- * - `{ Workspace: string }` — a named workspace reference resolved by the builder to a numeric ID
691
- * - `InstructionArg` — a fully-formed `{ Workspace: WorkspaceOffsetId }` or `{ Literal: string }`
692
- */
693
- export declare type NamedArg = {
694
- Workspace: string;
695
- } | InstructionArg;
696
-
697
- /**
698
- * Tari network identifiers. Values match the Rust `Network` byte representation.
699
- */
700
- export declare enum Network {
701
- MainNet = 0,
702
- StageNet = 1,
703
- NextNet = 2,
704
- LocalNet = 16,
705
- Igor = 36,
706
- Esmeralda = 38
707
- }
708
-
709
- /**
710
- * CBOR-encode a `NonFungibleAddress` as `Tag(130, [ResourceAddress, NonFungibleId])`.
711
- * The inner pair is minicbor's struct-as-array layout; the `NonFungibleId` enum
712
- * is its two-element `[variant_index, [field]]` form.
713
- *
714
- * @throws {InvalidArgumentError} if the resource address or id payload is malformed.
715
- */
716
- export declare function nonFungibleAddressLiteral(address: NonFungibleAddress): InstructionArg;
717
-
718
- /** Base class for every exception thrown by the Ootle SDK. */
719
- export declare abstract class OotleError extends Error {
720
- constructor(message: string, options?: ErrorOptions);
721
- }
722
-
723
- /**
724
- * A wallet that manages multiple key providers (one per component address) and
725
- * can sign transactions on behalf of any registered signer.
726
- *
727
- * Mirrors `OotleWallet` from the Rust ootle-rs crate.
728
- *
729
- * @example
730
- * ```ts
731
- * const wallet = new OotleWallet();
732
- * wallet.registerKeyProvider(myAddress, mySecretKeyWallet);
733
- * wallet.setDefaultSigner(myAddress);
734
- *
735
- * const signed = await wallet.authorizeTransaction(unsignedTx);
736
- * ```
737
- */
738
- export declare class OotleWallet implements Signer {
739
- private keyProviders;
740
- private defaultSignerAddress;
741
- constructor();
742
- /**
743
- * Registers a key provider (a `Signer`) for the given component address.
744
- *
745
- * Stealth capabilities (`getViewSecret`/`addStealthSignature`) are optional methods on
746
- * `Signer` (see {@link Signer}); the stealth spend authorizer uses them when present.
747
- */
748
- registerKeyProvider(address: string, provider: Signer): this;
749
- /**
750
- * Sets the address used when `signTransaction` is called without specifying a signer.
751
- *
752
- * @throws {KeyProviderNotFoundError} when no key provider has been registered for
753
- * `address`.
754
- */
755
- setDefaultSigner(address: string): this;
756
- /**
757
- * Returns the default signer address, or throws if none is set.
758
- *
759
- * @throws {DefaultSignerNotSetError} when no default signer is configured.
760
- */
761
- getAddress(): Promise<string>;
762
- /**
763
- * @throws {DefaultSignerNotSetError} when no default signer is configured.
764
- * @throws {KeyProviderNotFoundError} when the default address has no registered provider.
765
- */
766
- getPublicKey(): Promise<Uint8Array>;
767
- /**
768
- * Signs using the default signer.
769
- *
770
- * @throws {DefaultSignerNotSetError} when no default signer is configured.
771
- * @throws {KeyProviderNotFoundError} when the default address has no registered provider.
772
- */
773
- signTransaction(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionSignature[]>;
774
- /**
775
- * Generates `TransactionAuthorization` (signatures) for a specific registered signer.
776
- * Mirrors `OotleWallet::authorize_transaction` from ootle-rs.
777
- *
778
- * @throws {KeyProviderNotFoundError} when no provider is registered for `signerAddress`.
779
- */
780
- authorizeTransaction(signerAddress: string, unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionAuthorization>;
781
- /**
782
- * Collects authorizations from all registered key providers.
783
- * Useful when a transaction requires multiple signers.
784
- */
785
- authorizeTransactionAll(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionAuthorization[]>;
786
- /**
787
- * Returns the key provider for a specific address, if registered.
788
- */
789
- getKeyProvider(address: string): Signer | undefined;
790
- /**
791
- * Returns all registered signer addresses.
792
- */
793
- getSignerAddresses(): string[];
794
- private getSignerOrThrow;
795
- private requireKeyProvider;
796
- }
797
-
798
- /** Raised when an in-flight operation was cancelled by the caller. */
799
- export declare class OperationCancelledError extends OotleError {
800
- }
801
-
802
- /**
803
- * A stealth output to create.
804
- *
805
- * Use {@link createOutput} to construct one with the conventional defaults
806
- * (`payTo = { StealthPublicKey: {} }`, `minimumValuePromise = 0n`) and
807
- * validation (rejects `amount <= 0n`).
808
- */
809
- export declare interface Output {
810
- /** Destination account address (a string component/account address). */
811
- destination: string;
812
- /** µTari amount to send (must be `> 0n`). */
813
- amount: bigint;
814
- /** Resource being transferred. */
815
- resourceAddress: ResourceAddress;
816
- /** Resource view key — set only for resources with a viewable balance. */
817
- resourceViewKey?: Uint8Array;
818
- /** Optional structured memo attached to the output. */
819
- memo?: object;
820
- /** Spend condition for the output; defaults to `{ StealthPublicKey: {} }`. */
821
- payTo: object;
822
- /** Minimum value promise (range-proof lower bound); defaults to `0n`. */
823
- minimumValuePromise: bigint;
824
- }
825
-
826
- /** Fields callers supply to {@link createOutput}; `payTo` and `minimumValuePromise` are defaulted. */
827
- export declare interface OutputInit {
828
- destination: string;
829
- amount: bigint;
830
- resourceAddress: ResourceAddress;
831
- resourceViewKey?: Uint8Array;
832
- memo?: object;
833
- payTo?: object;
834
- minimumValuePromise?: bigint;
835
- }
836
-
837
- /** A parsed, spendable UTXO: its commitment (from the id) plus the on-chain output body. */
838
- export declare interface ParsedUtxo {
839
- /** 32-byte Pedersen commitment, derived from the substate id via {@link commitmentOf}. */
840
- commitment: Uint8Array;
841
- /** The on-chain output body (`public_nonce`, `encrypted_data`, ...). */
842
- body: OutputBody;
843
- }
844
-
845
- /**
846
- * A parsed workspace key string into an object with name and optional offset.
847
- *
848
- * Examples:
849
- * "bucket" -> { name: "bucket", offset: null }
850
- * "bucket.0" -> { name: "bucket", offset: 0 }
851
- */
852
- export declare interface ParsedWorkspaceKey {
853
- name: string;
854
- offset: number | null;
855
- }
856
-
857
- /**
858
- * Parse a fetched substate into a {@link ParsedUtxo}, or `null` when it is not a
859
- * live, spendable stealth UTXO.
860
- *
861
- * Returns `null` when:
862
- * - the substate is not the `Utxo` arm of {@link SubstateValue} (e.g. a component/vault),
863
- * - the UTXO has been spent (`output === null`),
864
- * - the UTXO is frozen (`is_frozen === true`),
865
- * - or the substate id does not yield a valid 32-byte commitment.
866
- *
867
- * @param substate - The fetched substate response.
868
- * @param substateId - The substate id the response was fetched by (source of the commitment).
869
- */
870
- export declare function parseSubstateUtxo(substate: IndexerGetSubstateResponse, substateId: string): ParsedUtxo | null;
871
-
872
- /**
873
- * Parses a workspace key string, supporting dot-notation offsets.
874
- *
875
- * @example
876
- * parseWorkspaceStringKey("bucket") // { name: "bucket", offset: null }
877
- * parseWorkspaceStringKey("bucket.0") // { name: "bucket", offset: 0 }
878
- * parseWorkspaceStringKey("bucket.1") // { name: "bucket", offset: 1 }
879
- *
880
- * @throws {InvalidArgumentError} if the key contains more than one dot, or if the
881
- * suffix after the dot is empty / non-numeric / negative.
882
- */
883
- export declare function parseWorkspaceStringKey(key: string): ParsedWorkspaceKey;
884
-
885
- /**
886
- * Patch the single stealth instruction in `unsignedTx` with a (hydrated) statement.
887
- *
888
- * Locates the sole `StealthTransfer` instruction (throws if there is not exactly one) and
889
- * replaces its `statement` field with the byte-exact compact JSON of `statement` (via the
890
- * single encoding seam in `instruction.ts`). Returns a new `UnsignedTransactionV1` — the
891
- * input is not mutated.
892
- *
893
- * @throws {InvalidArgumentError} when there is no StealthTransfer instruction (not a
894
- * stealth tx) or more than one (malformed).
895
- */
896
- export declare function patchStealthStatement(unsignedTx: UnsignedTransactionV1, statement: StealthTransferStatement): UnsignedTransactionV1;
897
-
898
- /**
899
- * A Provider reads chain state and submits transactions. It has no signing capability.
900
- * The canonical implementation is IndexerProvider, which talks to the indexer REST API.
901
- */
902
- export declare interface Provider {
903
- /** Returns the network this provider is connected to. */
904
- network(): Network;
905
- /**
906
- * Returns the epoch the network is currently on.
907
- *
908
- * Every transaction carries a mandatory `max_epoch`, capped at
909
- * `MAX_TRANSACTION_VALIDITY_EPOCHS` past this value, so a builder needs the chain tip
910
- * before it can be constructed: `TransactionBuilder.new(network, await
911
- * provider.getCurrentEpoch() + 10)`.
912
- */
913
- getCurrentEpoch(): Promise<number>;
914
- /** Fetches a single substate by ID and optional version. */
915
- getSubstate(substateId: string, version?: number | null): Promise<IndexerGetSubstateResponse>;
916
- /**
917
- * Fetches a stealth UTXO substate by resource address + 32-byte commitment.
918
- *
919
- * The provider owns the `utxo_{resourceHex}_{commitmentHex}` id format; callers pass
920
- * the resource and commitment and never string the id themselves. Returns `null` when
921
- * the UTXO does not exist (already spent / never created), instead of throwing.
922
- */
923
- getStealthUtxo(resourceAddress: string, commitment: Uint8Array): Promise<IndexerGetSubstateResponse | null>;
924
- /** Fetches multiple substates by ID in a single request. */
925
- fetchSubstates(requests: SubstateId[]): Promise<GetSubstatesResponse>;
926
- /** Returns the ABI definition for a published template. */
927
- getTemplateDefinition(templateAddress: string): Promise<GetTemplateDefinitionResponse>;
928
- /**
929
- * Submits a BOR+base64-encoded transaction envelope to the network.
930
- * Encoding is performed by `sealTransaction` in `transaction.ts`.
931
- */
932
- submitTransaction(envelope: TransactionEnvelope): Promise<IndexerSubmitTransactionResponse>;
933
- /** Polls for the result of a previously submitted transaction. */
934
- getTransactionResult(transactionId: string): Promise<IndexerGetTransactionResultResponse>;
935
- /**
936
- * Resolves unversioned inputs by fetching their current version from the indexer.
937
- * Returns the same list with `version` filled in for any entry that had `version: null`.
938
- */
939
- resolveInputs(inputs: SubstateRequirement[]): Promise<SubstateRequirement[]>;
940
- /** Lists recent transactions. */
941
- listRecentTransactions(params: ListRecentTransactionsRequest): Promise<ListRecentTransactionsResponse>;
942
- }
943
-
944
- /**
945
- * CBOR-encode a `RistrettoPublicKeyBytes` as a 32-byte CBOR byte string. A
946
- * compressed Ristretto point is *not* a tagged value — it is a bare byte string,
947
- * the same shape {@link bytesLiteral} produces. Accepts a 64-hex-char string or
948
- * a 32-byte `Uint8Array`; this wrapper exists so the public-key intent and the
949
- * length check are explicit at the call site.
950
- *
951
- * @throws {InvalidArgumentError} if the key is not exactly 32 bytes.
952
- */
953
- export declare function publicKeyLiteral(value: RistrettoPublicKeyBytes | Uint8Array): InstructionArg;
954
-
955
- /**
956
- * A stealth input resolved during {@link WalletStealthAuthorizer.prepare}: the input being
957
- * spent, its owner address (the one-time signer), the recovered blinding mask, and the
958
- * sender public nonce read from the fetched UTXO body (the DH counterparty for one-time
959
- * signing). Insertion-ordered, matching `spec.inputs`.
960
- */
961
- declare interface ResolvedStealthInput {
962
- ownerAddr: string;
963
- input: StealthInput;
964
- mask: Mask;
965
- /** The fetched UTXO's sender public nonce (`OutputBody.public_nonce`), raw bytes. */
966
- publicNonce: Uint8Array;
967
- }
968
-
969
- /**
970
- * Reads the chain tip and returns the `max_epoch` a transaction built now should carry:
971
- * `currentEpoch + leadEpochs`.
972
- *
973
- * ```ts
974
- * const builder = TransactionBuilder.new(provider.network(), await resolveMaxEpoch(provider));
975
- * ```
976
- *
977
- * @throws {InvalidArgumentError} if `leadEpochs` is not a positive integer, or exceeds
978
- * {@link MAX_TRANSACTION_VALIDITY_EPOCHS} (which the network would reject with
979
- * `AbortReason::ValidityWindowTooLong`).
980
- */
981
- export declare function resolveMaxEpoch(provider: Provider, leadEpochs?: number): Promise<number>;
982
-
983
- /**
984
- * Resolves unversioned inputs in the unsigned transaction by fetching their current
985
- * version from the provider.
986
- */
987
- export declare function resolveTransaction(provider: Provider, unsignedTx: UnsignedTransactionV1): Promise<UnsignedTransactionV1>;
988
-
989
- /**
990
- * CBOR-encode a `ResourceAddress` as `Tag(131, bytes(32))`. Accepts either the
991
- * `resource_<hex>` form or the bare 64-hex-char tail.
992
- *
993
- * @throws {InvalidArgumentError} if the address body is not 32 bytes (64 hex chars).
994
- */
995
- export declare function resourceAddressLiteral(address: ResourceAddress): InstructionArg;
996
-
997
- /**
998
- * A seal keypair: the throwaway key the seal signature is produced with.
999
- *
1000
- * Both fields are expected to be exactly 32 bytes. The length invariant is
1001
- * enforced at the trust boundary (in {@link signTransaction}) rather than via
1002
- * a branded type — see the README scope decision on asserted-`Uint8Array` as
1003
- * the default for non-stealth 32-byte values.
1004
- */
1005
- export declare interface SealKeypair {
1006
- secret_key: Uint8Array;
1007
- public_key: Uint8Array;
1008
- }
1009
-
1010
- /**
1011
- * BOR-encodes a {@link SignedTransaction} into a TransactionEnvelope.
1012
- *
1013
- * Encodes the byte-exact `sealedJson` directly (never the parsed `transaction` view), so
1014
- * u64 amounts above 2^53 are not corrupted by a `JSON.parse` → `JSON.stringify` round-trip.
1015
- */
1016
- export declare function sealTransaction(signed: SignedTransaction): TransactionEnvelope;
1017
-
1018
- /**
1019
- * Like `sendTransaction` but sets `dry_run = true` on the transaction before
1020
- * submitting, so the network simulates execution without committing state.
1021
- */
1022
- export declare function sendDryRun(provider: Provider, signers: Signer | Signer[], unsignedTx: UnsignedTransactionV1, watchOpts?: WatchOptions): Promise<IndexerGetTransactionResultResponse>;
1023
-
1024
- /**
1025
- * All-in-one convenience function: resolve → sign → encode → submit → watch.
1026
- */
1027
- export declare function sendTransaction(provider: Provider, signers: Signer | Signer[], unsignedTx: UnsignedTransactionV1, watchOpts?: WatchOptions): Promise<IndexerGetTransactionResultResponse>;
1028
-
1029
- /**
1030
- * Serialize an unsigned transaction to the JSON string handed to WASM (`addTransactionSigner`,
1031
- * `sealTransaction`) and to one-time stealth-signature hashing.
1032
- *
1033
- * Identical to `JSON.stringify(unsignedTx)` for any fragment-free transaction — so existing
1034
- * transaction hashes do not shift — but a stealth `statement` is carried as a
1035
- * {@link RawJsonFragment} whose byte-exact `toCompactJson()` string must survive verbatim. Its
1036
- * u64 amounts are bare JSON numbers exceeding 2^53; `JSON.stringify` cannot emit them
1037
- * losslessly. We therefore stringify each carrier as a unique placeholder, then splice the raw
1038
- * fragment in place of the quoted placeholder, never round-tripping the amounts through a JS
1039
- * number.
1040
- *
1041
- * Any `bigint` field (e.g. a large `nonce`) is emitted as a decimal *string*, matching the
1042
- * Tari clients' wire encoding: every 64-bit field on these APIs accepts a string as well as a
1043
- * number, and a string is the only lossless encoding above `Number.MAX_SAFE_INTEGER`. Plain
1044
- * `JSON.stringify` throws on a `bigint`, and the global `BigInt.prototype.toJSON` patch the
1045
- * client packages used to install was removed in 0.39.
1046
- */
1047
- export declare function serializeUnsignedTx(unsignedTx: UnsignedTransactionV1): string;
1048
-
1049
- /**
1050
- * Sign the balance proof over an inputs + outputs statement pair.
1051
- *
1052
- * A transfer with **no stealth inputs** uses `inputMask = Mask.zero()`; a
1053
- * **fully-revealed** transfer omits the balance proof entirely (not called here).
1054
- *
1055
- * @returns The `(public_nonce, signature)` balance-proof signature.
1056
- */
1057
- export declare function signBalanceProof(crypto: StealthCryptoProvider, inputMask: Mask, outputMask: Mask, inputsStatement: StealthInputsStatement, outputsStatement: StealthOutputsStatement): Promise<BalanceProofSignature>;
1058
-
1059
- /**
1060
- * A signed transaction produced by {@link signTransaction}, ready to be sealed.
1061
- *
1062
- * Carries the byte-exact `sealedJson` string emitted by WASM **alongside** a parsed
1063
- * {@link Transaction} view. The two are intentionally separate:
1064
- *
1065
- * - `sealedJson` is the **canonical artifact**. It preserves u64 amounts that exceed
1066
- * `Number.MAX_SAFE_INTEGER` (e.g. a confidential output's `minimum_value_promise`),
1067
- * which the engine emits as bare JSON numbers. {@link sealTransaction} BOR-encodes
1068
- * this string directly — it never re-stringifies the parsed object.
1069
- * - `transaction` is a **convenience view for inspection only**. It is the result of
1070
- * `JSON.parse(sealedJson)`, so any bare integer above 2^53 has already been rounded.
1071
- * Re-serialising it (`JSON.stringify`) and submitting that is lossy — always seal via
1072
- * `sealedJson`.
1073
- */
1074
- export declare interface SignedTransaction {
1075
- /** The byte-exact sealed-transaction JSON from WASM — the canonical bytes to BOR-encode. */
1076
- readonly sealedJson: string;
1077
- /**
1078
- * Parsed view of {@link sealedJson} for inspection. Lossy for u64 amounts > 2^53 — do
1079
- * NOT re-serialise this for submission; seal via {@link sealedJson} instead.
1080
- */
1081
- readonly transaction: Transaction;
1082
- }
1083
-
1084
- /**
1085
- * A Signer is responsible only for signing. It has no read or submit capability.
1086
- * Implementations include SecretKeyWallet (local WASM signing) and WalletDaemonSigner (remote daemon).
1087
- */
1088
- export declare interface Signer {
1089
- /** Returns the component address derived from this signer's public key. */
1090
- getAddress(): Promise<string>;
1091
- /** Returns the raw public key bytes for this signer. */
1092
- getPublicKey(): Promise<Uint8Array>;
1093
- /**
1094
- * Signs the given unsigned transaction and returns the collected signatures.
1095
- *
1096
- * `sealPublicKey` is mixed into the transaction hash
1097
- * (`hashUnsignedTransaction(JSON.stringify(tx), sealPublicKey)`) so every signature in the
1098
- * final envelope verifies against the SAME hash — the engine's seal verification enforces
1099
- * this. Implementations MUST hash with the supplied `sealPublicKey`, not their own.
1100
- */
1101
- signTransaction(transaction: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionSignature[]>;
1102
- /**
1103
- * Returns the view-only secret for stealth scanning/spending, if this signer holds one.
1104
- *
1105
- * **Optional** — a signer may not hold a view secret (e.g. `EphemeralKeySigner` has no
1106
- * view key; `WalletDaemonSigner` keeps it server-side). The spend authorizer treats this
1107
- * as a fallback: it takes the view secret explicitly from the transfer spec and only
1108
- * calls this when the spec does not carry one.
1109
- */
1110
- getViewSecret?(): Promise<Uint8Array>;
1111
- /**
1112
- * Produces a one-time spend-key signature for a stealth input.
1113
- *
1114
- * The signer derives the one-time spend scalar (`c + k`) for the owned stealth UTXO via
1115
- * `ctx.crypto.stealthDhSecret(...)` and signs the transaction hash with it.
1116
- *
1117
- * **Optional** — only signers that hold the owner secret (e.g. `SecretKeyWallet`) can
1118
- * implement this. Daemon-delegated stealth is server-side and out of scope here.
1119
- *
1120
- * @param unsignedJson - The (compact) JSON of the unsigned transaction to hash + sign.
1121
- * @param publicNonce - The stealth output's sender public nonce (the DH counterparty).
1122
- * @param sealPublicKey - The seal signer's public key, mixed into the transaction hash
1123
- * (mirrors the `hashUnsignedTransaction` arg used by {@link Signer.signTransaction}).
1124
- * @param ctx - Injected crypto seam, so the signer never imports WASM directly.
1125
- */
1126
- addStealthSignature?(unsignedJson: string, publicNonce: Uint8Array, sealPublicKey: Uint8Array, ctx: {
1127
- crypto: SignerStealthCrypto;
1128
- }): Promise<TransactionSignature>;
1129
- }
1130
-
1131
- /** Raised when a {@link Signer} fails to sign, seal, or expose required material. */
1132
- export declare class SignerError extends OotleError {
1133
- }
1134
-
1135
- /**
1136
- * The exact subset of `StealthCryptoProvider` that {@link Signer.addStealthSignature} needs.
1137
- *
1138
- * Defined here alongside `Signer` so the stealth-agnostic core never depends on the stealth
1139
- * module's full surface. The wider `StealthCryptoProvider` is structurally a supertype, so
1140
- * `WasmStealthCrypto` and `FakeStealthCrypto` flow through as-is.
1141
- */
1142
- export declare interface SignerStealthCrypto {
1143
- stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
1144
- }
1145
-
1146
- /**
1147
- * Collects signatures from all provided signers and assembles a signed transaction.
1148
- *
1149
- * Returns a {@link SignedTransaction} carrying the byte-exact `sealedJson` (the canonical
1150
- * bytes {@link sealTransaction} BOR-encodes) plus a parsed `transaction` view for
1151
- * inspection. The sealed JSON is **not** round-tripped through `JSON.parse`/`JSON.stringify`
1152
- * on its way to the envelope, so u64 amounts above 2^53 (e.g. a confidential output's
1153
- * `minimum_value_promise`) survive byte-exact.
1154
- *
1155
- * @param sealKeypair - Optional pre-generated seal keypair. When omitted, a fresh one is
1156
- * generated internally (the default for the plain transaction flow). The stealth spend
1157
- * authorizer passes one so the **same** seal public key flows into its one-time
1158
- * spend-key authorizations (which hash the tx with the seal public key) and into this
1159
- * final seal — otherwise those signatures would be over a different hash and fail to
1160
- * verify.
1161
- */
1162
- export declare function signTransaction(signers: Signer[], unsignedTx: UnsignedTransactionV1, sealKeypair?: SealKeypair): Promise<SignedTransaction>;
1163
-
1164
- /**
1165
- * Carry a {@link StealthTransferStatement} into an instruction as a byte-exact raw JSON
1166
- * fragment.
1167
- *
1168
- * The statement's u64 amounts are bare JSON numbers that routinely exceed 2^53; `JSON.parse`
1169
- * would round them and break the signed proofs. We therefore embed the canonical
1170
- * {@link StealthTransferStatement.toCompactJson} string verbatim under {@link RAW_JSON_FRAGMENT}
1171
- * and let {@link serializeUnsignedTx} splice it into the serialized transaction at signing /
1172
- * sealing / hashing time — never round-tripping it through a JS number. The engine still
1173
- * deserialises `statement` as a struct (not a string); the splice produces exactly that.
1174
- *
1175
- * Nothing reads the statement object structurally after it is set (the serializers stringify
1176
- * it wholesale and {@link patchStealthStatement} replaces the whole field), so the documented
1177
- * cast to the binding's structured type is sound.
1178
- */
1179
- export declare function statementAsWire(statement: StealthTransferStatement): StealthTransferStatement_2;
1180
-
1181
- /**
1182
- * The single seam that hides all `@tari-project/ootle-wasm` crypto behind a
1183
- * typed, byte/bigint interface returning the SDK's domain types.
1184
- *
1185
- * Every higher layer depends on **this interface**, never on raw WASM, so
1186
- * tests can inject a {@link FakeStealthCrypto fake}. The only real
1187
- * implementation is {@link WasmStealthCrypto}.
1188
- *
1189
- * All methods are **async even though the WASM is synchronous** to leave room
1190
- * for a future off-thread / worker-backed provider without churning call sites.
1191
- */
1192
- export declare interface StealthCryptoProvider {
1193
- /**
1194
- * Build the outputs (sender) side of a transfer: one witness per spec, aggregated
1195
- * into a canonical WASM outputs-statement plus the summed output mask.
1196
- *
1197
- * @param specs - The outputs to create (incl. change).
1198
- * @param revealedOutputAmount - The un-confidential (revealed) µTari output amount.
1199
- * @param revealedReceiver - The 32-byte public key allowed to take the revealed output
1200
- * (tari-ootle#2645: the engine requires its badge in the transaction's auth scope). Required
1201
- * when `revealedOutputAmount > 0`, ignored otherwise.
1202
- * @returns The WASM-produced {@link StealthOutputsStatement} and the aggregated
1203
- * `outputMask` for the balance proof.
1204
- */
1205
- generateOutputsStatement(specs: Output[], revealedOutputAmount: bigint, revealedReceiver?: Uint8Array): Promise<{
1206
- statement: StealthOutputsStatement;
1207
- outputMask: Mask;
1208
- }>;
1209
- /**
1210
- * Build the inputs (spend) side of a transfer as canonical WASM wire JSON.
1211
- *
1212
- * @param inputs - The stealth inputs being spent (empty for a revealed-only spend).
1213
- * @param revealedAmount - The un-confidential (revealed) µTari input amount.
1214
- * @returns A {@link StealthInputsStatement} carrying the WASM-produced `statementJson`.
1215
- */
1216
- buildInputsStatement(inputs: StealthInput[], revealedAmount: bigint): Promise<StealthInputsStatement>;
1217
- /**
1218
- * Sign the balance proof over the two statements' canonical wire JSONs.
1219
- *
1220
- * A transfer with **no stealth inputs** passes `inputMask = Mask.zero()`.
1221
- *
1222
- * @returns The `(public_nonce, signature)` balance-proof signature.
1223
- */
1224
- generateBalanceProofSignature(inputMask: Mask, outputMask: Mask, inputsStatementJson: string, outputsStatementJson: string): Promise<BalanceProofSignature>;
1225
- /**
1226
- * Optional client-side pre-flight check of a balance-proof signature. The
1227
- * engine is authoritative at submission — implement as a cheap debug aid only.
1228
- */
1229
- validateBalanceProofSignature?(proof: BalanceProofSignature, inputsStatementJson: string, outputsStatementJson: string): Promise<boolean>;
1230
- /**
1231
- * Derive the 32-byte AEAD encryption key for an output's encrypted data via DH+KDF.
1232
- *
1233
- * - Receivers: `(viewSecret, sender_public_nonce)`.
1234
- * - Senders: `(sender_secret_nonce, recipient_view_pub)`.
1235
- *
1236
- * Split from {@link unblindOutput} to mirror the WASM (`encryptedDataDhKdfAead` then
1237
- * `unblindOutput`).
1238
- */
1239
- deriveAeadKey(privateKey: Uint8Array, publicKey: Uint8Array): Promise<Uint8Array>;
1240
- /**
1241
- * Decrypt an owned output using a precomputed AEAD key (from {@link deriveAeadKey}).
1242
- *
1243
- * **Throws** on AEAD failure / commitment mismatch — i.e. the output is *not owned*.
1244
- * The receive helper catches this to mean "skip this UTXO".
1245
- *
1246
- * @param commitment - The output's 32-byte Pedersen commitment (from its substate id).
1247
- * @param encryptedData - The raw ciphertext bytes.
1248
- * @param aeadKey - The 32-byte AEAD key from {@link deriveAeadKey}.
1249
- * @param skipMemo - When `true`, the memo is not decrypted.
1250
- */
1251
- unblindOutput(commitment: Uint8Array, encryptedData: Uint8Array, aeadKey: Uint8Array, skipMemo: boolean): Promise<DecryptedData>;
1252
- /**
1253
- * Aggregate input commitment masks into a single scalar. `masks` must be
1254
- * non-empty; the revealed-only case (no stealth inputs) must short-circuit
1255
- * to `Mask.zero()` at the caller instead of calling this method.
1256
- */
1257
- aggregateInputMasks(masks: Mask[]): Promise<Mask>;
1258
- /**
1259
- * Derive the one-time stealth spend scalar (`c + k`) via DH for an owned stealth UTXO.
1260
- *
1261
- * @param networkByte - The network byte (see `Network`).
1262
- * @param ownerSecret - The owner's secret key.
1263
- * @param publicNonce - The output's sender public nonce.
1264
- * @returns The 32-byte spend scalar.
1265
- */
1266
- stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
1267
- /**
1268
- * Structurally validate a complete transfer envelope (balance proof filled). **Throws**
1269
- * on invalid. This is a client pre-flight (`view_key = null`); the engine is
1270
- * authoritative for viewable-resource validation at submission.
1271
- */
1272
- validateTransfer(statement: StealthTransferStatement): Promise<void>;
1273
- }
1274
-
1275
- /**
1276
- * A stealth input being spent, identified by its 32-byte Pedersen commitment.
1277
- */
1278
- export declare class StealthInput extends Bytes32 {
1279
- constructor(commitment: Uint8Array);
1280
- /** 32-byte commitment (defensive copy). */
1281
- get commitment(): Uint8Array;
1282
- toJSON(): StealthInputJson;
1283
- static fromJSON(json: StealthInputJson): StealthInput;
1284
- }
1285
-
1286
- /** Wire shape of a {@link StealthInput}. */
1287
- declare interface StealthInputJson {
1288
- commitment: string;
1289
- }
1290
-
1291
- /**
1292
- * The inputs side of a stealth transfer: the commitments being spent plus the
1293
- * revealed (un-confidential) input amount.
1294
- *
1295
- * **The signed/wire JSON is produced by WASM**, not hand-rolled. This type
1296
- * carries `(inputs, revealedAmount)` plus an optional cached `statementJson`
1297
- * (the WASM-produced wire string). Its `toJSON()` is a **debug/structural**
1298
- * view only — it is NOT the signed wire payload; the crypto seam fills and
1299
- * reads `statementJson` for that.
1300
- */
1301
- export declare class StealthInputsStatement {
1302
- readonly inputs: StealthInput[];
1303
- readonly revealedAmount: bigint;
1304
- /** Cached WASM-produced wire JSON (the canonical signed payload), once computed. */
1305
- statementJson?: string;
1306
- constructor(inputs: StealthInput[], revealedAmount: bigint, statementJson?: string);
1307
- /** Revealed-only inputs statement (no confidential inputs). */
1308
- static revealedOnly(amount: bigint): StealthInputsStatement;
1309
- /**
1310
- * Structural view (NOT the signed wire payload — see class docs). Amounts are
1311
- * decimal strings to keep `bigint` out of JSON.
1312
- */
1313
- toJSON(): {
1314
- inputs: StealthInputJson[];
1315
- revealed_amount: string;
1316
- };
1317
- static fromJSON(json: {
1318
- inputs: StealthInputJson[];
1319
- revealed_amount: string;
1320
- }): StealthInputsStatement;
1321
- }
1322
-
1323
- /**
1324
- * The outputs side of a stealth transfer.
1325
- *
1326
- * Carries the **WASM-produced** wire payload verbatim. The internal field
1327
- * names of that JSON are owned by the engine and are not modelled here.
1328
- */
1329
- export declare class StealthOutputsStatement {
1330
- /** The canonical, WASM-produced outputs-statement wire JSON. */
1331
- readonly statementJson: string;
1332
- constructor(statementJson: string);
1333
- /** Parse the carried JSON into a plain object view (the engine owns the shape). */
1334
- parsed(): unknown;
1335
- /** The carried wire JSON string is already canonical. */
1336
- toJSON(): string;
1337
- /** Reconstruct from a wire JSON string. */
1338
- static fromJSON(statementJson: string): StealthOutputsStatement;
1339
- }
1340
-
1341
- /**
1342
- * Fluent builder for a confidential (stealth) transfer.
1343
- *
1344
- * Supports the full input/output matrix: spend revealed input (withdraw from a vault)
1345
- * and/or one or more confidential UTXOs ({@link spendStealthInput}), emit one or more
1346
- * stealth outputs (+ optional revealed change), and a fee. The balance equation
1347
- * (revealed-in + stealth-in == stealth-out + revealed-out) must hold; the stealth-input
1348
- * value is carried by each input's mask, recovered by the authorizer.
1349
- *
1350
- * @example
1351
- * ```ts
1352
- * const spec = await new StealthTransfer(provider, resourceAddress)
1353
- * .spendRevealedInput(account, 5n * TARI)
1354
- * .toStealthOutput(createOutput({ destination, amount: 3n * TARI, resourceAddress }))
1355
- * .toRevealedOutput(1n * TARI) // revealed change back to `account`
1356
- * .payFeeFromRevealed(1n * TARI)
1357
- * .prepare();
1358
- * ```
1359
- */
1360
- export declare class StealthTransfer {
1361
- private readonly provider;
1362
- private readonly crypto;
1363
- private builder;
1364
- private readonly state;
1365
- /** Set by {@link withMaxEpoch}; `null` means {@link prepare} resolves one from the chain tip. */
1366
- private maxEpoch;
1367
- /** Guards against a second {@link prepare} re-emitting instructions into the same builder. */
1368
- private prepared;
1369
- /**
1370
- * When set, revealed change is captured as a bucket on the workspace under this name
1371
- * instead of being auto-deposited back to `revealedInput.source` — see
1372
- * {@link toRevealedOutputAsBucket}.
1373
- */
1374
- private revealedOutputBucketVar;
1375
- /**
1376
- * Extra instructions appended after the native `StealthTransfer` instruction (and its
1377
- * change-bucket handling), in the same transaction — see {@link andThen}. Lets a caller
1378
- * chain e.g. a custom contract call that consumes the bucket saved by
1379
- * {@link toRevealedOutputAsBucket}, all signed together by the authorizer in one
1380
- * transaction instead of needing a separate one.
1381
- */
1382
- private followUpInstructions;
1383
- /**
1384
- * The public key allowed to take the revealed output — see {@link withRevealedReceiver}.
1385
- */
1386
- private revealedReceiver;
1387
- /**
1388
- * @param provider - Read-only chain access (used by {@link prepare} to resolve inputs).
1389
- * @param resourceAddress - The resource being transferred.
1390
- * @param crypto - Injectable crypto seam; defaults to {@link WasmStealthCrypto}. Tests
1391
- * pass a {@link FakeStealthCrypto} for WASM-free runs.
1392
- */
1393
- constructor(provider: Provider, resourceAddress: ResourceAddress, crypto?: StealthCryptoProvider);
1394
- /**
1395
- * Withdraw `amount` of the transfer's resource from `account`'s revealed vault.
1396
- *
1397
- * All revealed input must come from a single account (the fee/change source). Calling
1398
- * this more than once accumulates the amount but the account must be the same.
1399
- *
1400
- * @throws {InvalidArgumentError} if `amount` is not `> 0`, or a different source
1401
- * account is supplied on a second call.
1402
- */
1403
- spendRevealedInput(account: ComponentAddress, amount: bigint): this;
1404
- /** Add a stealth output to create (repeatable). */
1405
- toStealthOutput(spec: Output): this;
1406
- /**
1407
- * Add revealed (un-confidential) change, returned to the revealed source account.
1408
- *
1409
- * @throws {InvalidArgumentError} if `amount` is not `> 0`.
1410
- */
1411
- toRevealedOutput(amount: bigint): this;
1412
- /**
1413
- * Like {@link toRevealedOutput}, but instead of auto-depositing the change back into
1414
- * `revealedInput.source`, the `StealthTransfer` instruction's bucket output is left on the
1415
- * workspace under `workspaceVarName` for {@link andThen}'s instructions (or a caller-supplied
1416
- * `withBuilder` continuation) to consume directly — e.g. passing it straight into a custom
1417
- * contract call in the same transaction, rather than requiring a second transaction that
1418
- * withdraws it back out again (which a plain `CallMethod withdraw` on a Stealth-typed vault
1419
- * cannot do standalone — see this class's own `emitInstructions` doc comment: the account
1420
- * template's `withdraw` only produces a valid bucket when paired with the native
1421
- * `StealthTransfer` instruction in the same transaction).
1422
- *
1423
- * A real `toStealthOutput` is still required elsewhere on this builder (`validate()` enforces
1424
- * it): the bundled `ootle-wasm@0.37.0` signer cannot parse a statement with zero stealth
1425
- * outputs at all — confirmed live, `signTransaction`'s own WASM call throws the generic "did
1426
- * not match any variant of untagged enum TransactionInput" error regardless of how
1427
- * `balance_proof` is represented. A small dust self-output (as `OotleAccount.
1428
- * withdrawStealthAndExecute` in tari-wallet-extension does) satisfies this cheaply.
1429
- *
1430
- * @throws {InvalidArgumentError} if `amount` is not `> 0`.
1431
- */
1432
- toRevealedOutputAsBucket(amount: bigint, workspaceVarName: string): this;
1433
- /**
1434
- * Name the public key allowed to take the revealed output (tari-ootle#2645). The engine
1435
- * requires that key's badge in the transaction's auth scope before it creates the revealed
1436
- * bucket, so it must be a key that signs the transaction — normally the account key, which
1437
- * {@link WalletStealthAuthorizer} signs with by default. Required whenever the transfer has a
1438
- * revealed output ({@link toRevealedOutput} / {@link toRevealedOutputAsBucket}).
1439
- *
1440
- * @throws {InvalidArgumentError} if `publicKey` is not 32 bytes.
1441
- */
1442
- withRevealedReceiver(publicKey: Uint8Array): this;
1443
- /**
1444
- * Append `instructions` after the native `StealthTransfer` instruction (and its bucket
1445
- * handling), so they run in the same signed transaction — typically consuming the bucket
1446
- * {@link toRevealedOutputAsBucket} saved to the workspace. Repeatable; each call appends.
1447
- */
1448
- andThen(instructions: Instruction[]): this;
1449
- /**
1450
- * Pay the transaction fee from the revealed source account (max `amount`).
1451
- *
1452
- * @throws {InvalidArgumentError} if no source account is set, or `amount` is not `> 0`.
1453
- */
1454
- payFeeFromRevealed(amount: bigint): this;
1455
- /**
1456
- * Set the transaction's validity window explicitly. Without this, {@link prepare}
1457
- * reads the current epoch from the provider and applies
1458
- * `DEFAULT_TRANSACTION_VALIDITY_EPOCHS`.
1459
- *
1460
- * @throws {InvalidArgumentError} if `maxEpoch` is not a non-negative integer.
1461
- */
1462
- withMaxEpoch(maxEpoch: number): this;
1463
- /** Escape hatch over the inner {@link TransactionBuilder} (e.g. extra instructions). */
1464
- withBuilder(fn: (b: TransactionBuilder) => TransactionBuilder): this;
1465
- /**
1466
- * Spend a confidential UTXO owned by `ownerAddr`, identified by its 32-byte
1467
- * `commitment`.
1468
- *
1469
- * Repeatable: each call adds another stealth input. Inputs are keyed by their
1470
- * **commitment hex alone** and de-duplicated — a second call with the same commitment
1471
- * throws, **regardless of the owner label**. A commitment uniquely identifies a UTXO
1472
- * within the builder's single resource and a UTXO has exactly one owner, so the same
1473
- * commitment under two different owner labels is still the same UTXO; accepting it twice
1474
- * would register the substate id twice and emit the commitment twice in the inputs
1475
- * statement — a self-double-spend the engine rejects. The owner address is recorded
1476
- * alongside the input so the authorizer can pick the one-time spend signer for each.
1477
- *
1478
- * The input's value contributes to the balance equation via its **mask** (recovered by
1479
- * the authorizer when it unblinds the UTXO), so the builder does not need the amount
1480
- * here — only the commitment.
1481
- *
1482
- * @throws {InvalidArgumentError} if `commitment` is not 32 bytes, or the same
1483
- * commitment is added twice (under any owner).
1484
- */
1485
- spendStealthInput(ownerAddr: string, commitment: Uint8Array): this;
1486
- /**
1487
- * Assemble the unsigned transaction and the (incomplete) transfer statement.
1488
- *
1489
- * 1. validate (≥1 input, ≥1 stealth output);
1490
- * 2. generate the outputs statement (+ aggregated output mask) via the crypto seam;
1491
- * 3. build the inputs statement (concatenated commitments + revealed input
1492
- * amount) and assemble an incomplete {@link StealthTransferStatement}
1493
- * (`balanceProof: undefined`);
1494
- * 4. emit instructions: revealed `withdraw` → `saveVar` → the native
1495
- * `StealthTransfer` instruction (+ deposit the revealed-change bucket);
1496
- * 5. register the revealed source account + every vault it references as tx
1497
- * inputs (otherwise the engine rejects `withdraw` / `pay_fee` with
1498
- * `SubstateNotFound`);
1499
- * 6. register each stealth input's UTXO substate id as a tx input so it is
1500
- * resolved / locked alongside the revealed inputs;
1501
- * 7. resolve substate versions via the provider;
1502
- * 8. return the {@link StealthTransferSpec}.
1503
- *
1504
- * Stealth-input **values** are carried by their masks (recovered later by the
1505
- * authorizer), not as amounts — there is no balance-equation check here when stealth
1506
- * inputs are present, because the builder does not know their values; the balance proof
1507
- * (which the authorizer signs over the recovered masks) is the authoritative check.
1508
- *
1509
- * @throws {InvalidArgumentError} if the builder is invalid (no inputs, no outputs,
1510
- * no stealth output, unbalanced revealed-only transfer, or revealed change without
1511
- * a revealed source) or `prepare` has already been called once.
1512
- */
1513
- prepare(): Promise<StealthTransferSpec>;
1514
- /**
1515
- * Build the ordered, de-duplicated list of addresses that must authorize the tx: the
1516
- * revealed source account first (if any), then each distinct stealth-input owner in the
1517
- * order it was first added.
1518
- */
1519
- private collectRequiredSigners;
1520
- /**
1521
- * Validate the builder before assembly: at least one input (revealed and/or stealth) and
1522
- * at least one stealth output, plus — for the revealed-only path — the balance equation
1523
- * `revealedInput.amount == stealthOut + revealedOut`.
1524
- *
1525
- * The fee is withdrawn separately by the fee instruction, not from the transferred
1526
- * amount. When stealth inputs are present, the per-input values are unknown to the builder
1527
- * (carried by masks), so the arithmetic check is **skipped** — the balance proof the
1528
- * authorizer signs is authoritative. We still surface obvious wiring mistakes early.
1529
- */
1530
- private validate;
1531
- /**
1532
- * Emit the instruction sequence into the inner builder:
1533
- * (revealed `withdraw` → `saveVar`)? → native `StealthTransfer` → deposit revealed change?
1534
- *
1535
- * The revealed `withdraw` and the `revealed_input_bucket` are emitted **only** when there
1536
- * is a revealed input amount; a stealth-input-only transfer passes a `null` bucket. The
1537
- * fee instruction (if any) was already added by {@link payFeeFromRevealed}.
1538
- */
1539
- private emitInstructions;
1540
- }
1541
-
1542
- /** The narrowed shape of the native `StealthTransfer` instruction variant. */
1543
- export declare type StealthTransferInstruction = Extract<Instruction, {
1544
- StealthTransfer: unknown;
1545
- }>;
1546
-
1547
- /**
1548
- * Encode the native `StealthTransfer` instruction. See the file header for the on-chain
1549
- * contract and the (probe-verified) statement-encoding rationale.
1550
- *
1551
- * The `revealed_input_bucket` references the saved withdraw bucket by name; the builder
1552
- * declared that name via `saveVar`, so the {@link WorkspaceOffsetId} `{ id, offset: null }`
1553
- * is resolved here against the same name → numeric id mapping the builder uses.
1554
- *
1555
- * @param init - The resource, revealed-input bucket name, and statement.
1556
- * @param resolveBucket - Maps a workspace var name to its {@link WorkspaceOffsetId}. The
1557
- * builder owns the name → id mapping; pass a resolver so this seam stays builder-agnostic.
1558
- */
1559
- export declare function stealthTransferInstruction(init: StealthTransferInstructionInit, resolveBucket: (name: string) => WorkspaceOffsetId): Instruction;
1560
-
1561
- /** Inputs to {@link stealthTransferInstruction}. */
1562
- export declare interface StealthTransferInstructionInit {
1563
- /** The resource being transferred. */
1564
- resourceAddress: ResourceAddress;
1565
- /**
1566
- * Workspace var name of the revealed-input bucket (from the `withdraw` + `saveVar`), or
1567
- * `null`/omitted for a stealth-input-only transfer.
1568
- */
1569
- revealedInputBucket: string | null;
1570
- /** The transfer statement (may be incomplete — `balanceProof` undefined — at build time). */
1571
- statement: StealthTransferStatement;
1572
- }
1573
-
1574
- /**
1575
- * The output of {@link StealthTransfer.prepare}: an unsigned transaction carrying the
1576
- * on-chain stealth instruction and an **incomplete** statement (`balanceProof:
1577
- * undefined`), plus the metadata the authorizer needs to finish it.
1578
- */
1579
- export declare interface StealthTransferSpec {
1580
- /** The unsigned transaction with substate versions resolved. */
1581
- unsignedTx: UnsignedTransactionV1;
1582
- /** The (incomplete) transfer statement; the authorizer fills `balanceProof`. */
1583
- statement: StealthTransferStatement;
1584
- /** The aggregated output blinding mask, needed to sign the balance proof. */
1585
- outputMask: Mask;
1586
- /** The builder state (resource, inputs, amounts) — consumed by the authorizer. */
1587
- state: StealthTransferState;
1588
- /**
1589
- * Addresses that must authorize the transaction. The revealed source account (when there
1590
- * is revealed input) is required first, followed by each distinct stealth-input owner
1591
- * (in first-seen order) — those owners supply the one-time spend-key authorizations.
1592
- */
1593
- requiredSigners: string[];
1594
- /**
1595
- * Ordered list of stealth inputs being spent, each paired with its owner address. Order
1596
- * matches the order `spendStealthInput` was called — required for the input-mask
1597
- * aggregation and inputs-statement build to agree on ordering.
1598
- */
1599
- inputs: Array<{
1600
- input: StealthInput;
1601
- owner: string;
1602
- }>;
1603
- }
1604
-
1605
- /** Mutable internal state accumulated by a {@link StealthTransfer} builder. */
1606
- export declare interface StealthTransferState {
1607
- resource: ResourceAddress;
1608
- /**
1609
- * The revealed-source account and the total amount withdrawn from it, or `null` for a
1610
- * stealth-input-only spend. Coupling the source and amount in one tagged field encodes the
1611
- * invariant — a revealed input always has a source — in the type system, so consumers can
1612
- * narrow without "unreachable" guards.
1613
- */
1614
- revealedInput: {
1615
- source: ComponentAddress;
1616
- amount: bigint;
1617
- } | null;
1618
- /**
1619
- * Stealth UTXOs to spend, keyed by their **commitment hex alone** (insertion-ordered,
1620
- * duplicates rejected). A commitment uniquely identifies a UTXO within the builder's
1621
- * single resource, and a UTXO has exactly one owner — so keying by commitment (not
1622
- * owner+commitment) prevents the same UTXO being registered twice under different owner
1623
- * labels, which the engine would reject as a self-double-spend. Each value carries the
1624
- * input alongside its owner address (the one-time spend signer). The `Map` preserves
1625
- * insertion order so the masks aggregate and the inputs statement is built in the
1626
- * **same** order — required for the balance proof to verify.
1627
- */
1628
- inputsToSpend: Map<string, {
1629
- input: StealthInput;
1630
- owner: string;
1631
- }>;
1632
- outputs: Output[];
1633
- revealedOutputAmount: bigint;
1634
- }
1635
-
1636
- /**
1637
- * The top-level stealth-transfer envelope assembled **in TS**.
1638
- *
1639
- * Combines the WASM-produced inputs/outputs statement JSONs with the balance-proof
1640
- * `(public_nonce, signature)`. `balanceProof` is `undefined` until the authorizer
1641
- * fills it in.
1642
- *
1643
- * Two distinct serialisations, intentionally separate:
1644
- *
1645
- * 1. **{@link toJSON} / {@link fromJSON}** — a purely *structural*, symmetric,
1646
- * lossless round-trip used by tests and any TS-only persistence. It does NOT
1647
- * re-parse WASM statement strings into JS numbers; the outputs side is carried as
1648
- * its raw wire string.
1649
- * 2. **{@link toCompactJson}** — the *signed wire form*. It embeds the
1650
- * WASM-produced statement strings **byte-exact** by string concatenation of raw
1651
- * canonical fragments — it **never** `JSON.parse`s a WASM string (raw u64 µTari
1652
- * amounts routinely exceed 2^53, so parse→number→re-stringify silently corrupts
1653
- * them and breaks the signature). This is the form fed to
1654
- * `validateStealthTransfer` and any hashing/signing path.
1655
- *
1656
- * The **byte-exactness of the WASM fragments** in {@link toCompactJson} is
1657
- * non-negotiable: the engine validates against the exact bytes signed.
1658
- */
1659
- export declare class StealthTransferStatement {
1660
- readonly inputsStatement: StealthInputsStatement;
1661
- readonly outputsStatement: StealthOutputsStatement;
1662
- balanceProof?: BalanceProofSignature;
1663
- constructor(inputsStatement: StealthInputsStatement, outputsStatement: StealthOutputsStatement, balanceProof?: BalanceProofSignature);
1664
- /**
1665
- * Structural view of the envelope (debug / lossless round-trip — NOT the signed
1666
- * wire form; see {@link toCompactJson}). The inputs side is the inputs statement's
1667
- * structural `toJSON()`; the outputs side is its **raw wire string**, carried
1668
- * verbatim (never parsed). `balance_proof` is omitted when undefined.
1669
- */
1670
- toJSON(): StealthTransferStatementJson;
1671
- /**
1672
- * The **signed wire form**: a single canonical compact JSON string in which the
1673
- * WASM-produced statement fragments are embedded byte-exact.
1674
- *
1675
- * Built by concatenating raw canonical fragments — it never `JSON.parse`s a WASM
1676
- * statement string, so raw u64 µTari amounts (which can exceed 2^53) survive
1677
- * uncorrupted. The inputs fragment prefers the cached WASM `statementJson` (the
1678
- * canonical signed bytes); it falls back to `JSON.stringify` of the structural
1679
- * inputs view only when no WASM string is present (the revealed-only / test case).
1680
- * The outputs fragment is always the raw WASM `statementJson` string. The
1681
- * balance-proof object is small, all-hex (no large integers), so it routes through
1682
- * `JSON.stringify` safely.
1683
- *
1684
- * @throws {InvalidArgumentError} if either statement fragment is not a JSON object.
1685
- */
1686
- toCompactJson(): string;
1687
- /** Reconstruct from the structural {@link toJSON} shape. Symmetric and lossless. */
1688
- static fromJSON(json: StealthTransferStatementJson): StealthTransferStatement;
1689
- }
1690
-
1691
- /**
1692
- * Structural wire shape of a {@link StealthTransferStatement} envelope.
1693
- *
1694
- * This is the **debug / round-trip** shape produced by `toJSON()` and consumed by
1695
- * `fromJSON()` — it is symmetric and lossless for a TS-only envelope. It is **NOT**
1696
- * the signed wire form: see {@link StealthTransferStatement.toCompactJson}.
1697
- *
1698
- * - `inputs` is the structural inputs-statement view (`{ inputs, revealed_amount }`).
1699
- * - `outputs` is the **raw `StealthOutputsStatement` wire string** (carried verbatim),
1700
- * never a parsed object — parsing-then-restringifying WASM u64 amounts is lossy.
1701
- */
1702
- declare interface StealthTransferStatementJson {
1703
- inputs: {
1704
- inputs: StealthInputJson[];
1705
- revealed_amount: string;
1706
- };
1707
- outputs: string;
1708
- balance_proof?: BalanceProofSignatureJson;
1709
- }
1710
-
1711
- /**
1712
- * Compose a stealth UTXO substate id from a resource address and a 32-byte commitment.
1713
- *
1714
- * The id format is `utxo_{resourceHex}_{commitmentHex}`, where `resourceHex` is the
1715
- * resource address with its `resource_` prefix stripped (a bare hex string is accepted
1716
- * verbatim). This is the inverse of {@link commitmentOf} and matches the id the
1717
- * `IndexerProvider.getStealthUtxo` fetch composes, so the spend builder can register a
1718
- * stealth input as a tx input **without** reaching into the concrete indexer client.
1719
- *
1720
- * @param resourceAddress - The resource address (`resource_<hex>`) or a bare hex string.
1721
- * @param commitment - The output's 32-byte Pedersen commitment.
1722
- * @returns The `utxo_{resourceHex}_{commitmentHex}` substate id.
1723
- */
1724
- export declare function stealthUtxoSubstateId(resourceAddress: string, commitment: Uint8Array): string;
1725
-
1726
- /** CBOR-encode a `String` as a CBOR text string. */
1727
- export declare function stringLiteral(value: string): InstructionArg;
1728
-
1729
- /**
1730
- * Submits an encoded transaction envelope and returns the transaction ID.
1731
- */
1732
- export declare function submitTransaction(provider: Provider, envelope: TransactionEnvelope): Promise<string>;
1733
-
1734
- export { SubstateId }
1735
-
1736
- export { SubstateRequirement }
1737
-
1738
- /**
1739
- * Native TARI (XTR) token resource address (object key `[1u8; 32]`). Used for
1740
- * all native-token transfers and stealth confidential outputs.
1741
- */
1742
- export declare const TARI_RESOURCE_ADDRESS = "resource_0101010101010101010101010101010101010101010101010101010101010101";
1743
-
1744
- /** A function that can be called on a published template. */
1745
- export declare interface TariFunctionDefinition {
1746
- templateAddress: PublishedTemplateAddress;
1747
- functionName: string;
1748
- args?: NamedArg[];
1749
- }
1750
-
1751
- /** A method that can be called on a component. */
1752
- export declare interface TariMethodDefinition {
1753
- methodName: string;
1754
- args?: NamedArg[];
1755
- /** Call by component address. Mutually exclusive with `fromWorkspace`. */
1756
- componentAddress?: ComponentAddress;
1757
- /** Call the component stored under this workspace key. Mutually exclusive with `componentAddress`. */
1758
- fromWorkspace?: string;
1759
- }
1760
-
1761
- /**
1762
- * CBOR-encode a `PublishedTemplateAddress` as `Tag(137, bytes(32))`. Accepts
1763
- * either the `template_<hex>` form or the bare 64-hex-char tail.
1764
- *
1765
- * @throws {InvalidArgumentError} if the address body is not 32 bytes (64 hex chars).
1766
- */
1767
- export declare function templateAddressLiteral(address: PublishedTemplateAddress): InstructionArg;
1768
-
1769
- /**
1770
- * Implemented by types that can produce a component address string.
1771
- * Mirrors the `ToAccountAddress` trait from ootle-rs.
1772
- */
1773
- export declare interface ToAccountAddress {
1774
- toAccountAddress(): string;
1775
- }
1776
-
1777
- export declare function toHexStr(uint8: Uint8Array): string;
1778
-
1779
- export { Transaction }
1780
-
1781
- /**
1782
- * The result of authorizing a transaction: a set of signatures from one signer.
1783
- * Mirrors `TransactionAuthorization` from the Rust ootle-rs crate.
1784
- */
1785
- export declare interface TransactionAuthorization {
1786
- signerAddress: string;
1787
- signatures: TransactionSignature[];
1788
- }
1789
-
1790
- /**
1791
- * Fluent builder for constructing UnsignedTransactionV1 objects.
1792
- *
1793
- * Only `buildUnsignedTransaction()` is exposed — signing is handled separately
1794
- * via the `Signer` interface and `signTransaction` flow function.
1795
- */
1796
- export declare class TransactionBuilder {
1797
- private unsignedTransaction;
1798
- private workspaceIds;
1799
- private feeWorkspaceIds;
1800
- /**
1801
- * `maxEpoch` is required: every transaction now carries a bounded validity window
1802
- * (`UnsignedTransactionV1.max_epoch`), so the last epoch in which it may be sequenced
1803
- * is decided up front rather than left open. The network rejects a window longer than
1804
- * {@link MAX_TRANSACTION_VALIDITY_EPOCHS} epochs past the current one with
1805
- * `AbortReason::ValidityWindowTooLong`, so derive it from the chain tip — e.g.
1806
- * `(await provider.getCurrentEpoch()) + 10`.
1807
- *
1808
- * @throws {InvalidArgumentError} if `maxEpoch` is not a non-negative integer.
1809
- */
1810
- constructor(network: Network | number, maxEpoch: number);
1811
- static new(network: Network | number, maxEpoch: number): TransactionBuilder;
1812
- callFunction<T extends TariFunctionDefinition>(func: T, args: Exclude<T["args"], undefined>): this;
1813
- /**
1814
- * @throws {InvalidArgumentError} if `method` provides neither `componentAddress`
1815
- * nor `fromWorkspace`, or if `fromWorkspace` references an undefined variable.
1816
- */
1817
- callMethod<T extends TariMethodDefinition>(method: T, args: Exclude<T["args"], undefined>): this;
1818
- createAccount(ownerPublicKey: string, workspaceBucket?: string): this;
1819
- createProof(account: ComponentAddress, resourceAddress: ResourceAddress): this;
1820
- claimBurn(claim: MinotariBurnClaimProof, output_data: ClaimBurnOutputData): this;
1821
- allocateAddress(allocatableType: AllocatableAddressType, workspaceIdName: string): this;
1822
- /**
1823
- * Saves the last instruction output to a named workspace variable.
1824
- * The variable can be referenced by subsequent instructions using `{ Workspace: "name" }`.
1825
- */
1826
- saveVar(name: string): this;
1827
- /**
1828
- * Adds a fee instruction that calls `pay_fee` on the given component.
1829
- * The component must call `vault.pay_fee` and reveal enough confidential XTR.
1830
- */
1831
- feeTransactionPayFromComponent(componentAddress: ComponentAddress, maxFee: bigint): this;
1832
- /**
1833
- * NOT IMPLEMENTED — always throws. A confidential `pay_fee` needs a
1834
- * `ConfidentialWithdrawProof` `Literal` that requires `tari_bor` struct encoding
1835
- * the TS SDK does not yet provide. Use {@link feeTransactionPayFromComponent} for
1836
- * revealed-fee payment.
1837
- *
1838
- * @throws {InvalidArgumentError} always.
1839
- */
1840
- feeTransactionPayFromComponentConfidential(_componentAddress: ComponentAddress, _proof: ConfidentialWithdrawProof): this;
1841
- dropAllProofsInWorkspace(): this;
1842
- /**
1843
- * Publishes a compiled WASM template. The binary is stored as a transaction
1844
- * blob and referenced by index from the `PublishTemplate` instruction.
1845
- *
1846
- * @param binaryBase64 the template WASM, standard-base64 encoded
1847
- * @param metadataHash optional multihash of off-chain CBOR metadata
1848
- */
1849
- publishTemplate(binaryBase64: string, metadataHash?: string | null): this;
1850
- addInstruction(instruction: Instruction): this;
1851
- addFeeInstruction(instruction: Instruction): this;
1852
- withInstructions(instructions: Instruction[]): this;
1853
- withFeeInstructions(instructions: Instruction[]): this;
1854
- /**
1855
- * Account for slots claimed by instructions the builder did not allocate itself, so a
1856
- * later `saveVar` cannot re-issue one. Rust does this inline in `add_instruction`.
1857
- */
1858
- private observeAllocations;
1859
- /**
1860
- * Build the fee instructions with a nested builder, mirroring the Rust builder's separate
1861
- * fee-instruction builder. The nested builder gets its own workspace scope — correct,
1862
- * because the engine clears the workspace between the fee and main instruction runs.
1863
- *
1864
- * Note this REPLACES any fee instructions already set, as it always has.
1865
- */
1866
- withFeeInstructionsBuilder(builder: (b: TransactionBuilder) => TransactionBuilder): this;
1867
- /**
1868
- * Declare a transaction input. Since tari-ootle#2640 every input declares read or write
1869
- * intent; a plain {@link SubstateRequirement} (no `is_write`) is declared a **write**, the
1870
- * engine's own default — over-declaring only locks more, under-declaring aborts execution.
1871
- */
1872
- addInput(input: SubstateRequirement | InputDeclaration): this;
1873
- withInputs(inputs: (SubstateRequirement | InputDeclaration)[]): this;
1874
- /** @throws {InvalidArgumentError} if `minEpoch` is not a non-negative integer. */
1875
- withMinEpoch(minEpoch: number): this;
1876
- /**
1877
- * Overrides the validity window set at construction. See the constructor for the
1878
- * network's cap on how far ahead of the current epoch this may sit.
1879
- *
1880
- * @throws {InvalidArgumentError} if `maxEpoch` is not a non-negative integer.
1881
- */
1882
- withMaxEpoch(maxEpoch: number): this;
1883
- /**
1884
- * Stamps the transaction nonce, which distinguishes otherwise-identical transactions.
1885
- *
1886
- * The transaction id excludes the seal signature's witness data, so two identical
1887
- * bodies sealed by the same key are the *same* transaction — submitting both executes
1888
- * once. Give each intent a distinct nonce when repeated submissions must each execute.
1889
- * Defaults to `0`.
1890
- *
1891
- * @throws {InvalidArgumentError} if `nonce` is negative or overflows u64.
1892
- */
1893
- withNonce(nonce: number | bigint): this;
1894
- /**
1895
- * Adopt an existing transaction and keep building on it.
1896
- *
1897
- * The adopted transaction is **copied**, not aliased: subsequent builder calls must not
1898
- * reach back into the caller's object. The manual co-signing flow ships
1899
- * `JSON.stringify(unsigned)` across a boundary, so mutating a transaction the caller has
1900
- * already serialized or signed makes the two sides disagree — surfacing only at submit
1901
- * time as the opaque engine error `"Transaction has one or more invalid signature(s)"`.
1902
- * This mirrors the copy {@link buildUnsignedTransaction} makes on the way out.
1903
- */
1904
- withUnsignedTransaction(unsignedTransaction: UnsignedTransactionV1): this;
1905
- /**
1906
- * Resolves a workspace variable name (supporting dot-notation offsets, e.g. `"bucket.0"`)
1907
- * to its `WorkspaceOffsetId`. The variable must have been declared by a prior `saveVar`
1908
- * (or other allocating call). Use this when constructing an `Instruction` that takes a
1909
- * `WorkspaceOffsetId` directly (e.g. the native `StealthTransfer` variant's
1910
- * `revealed_input_bucket`), where the builder's automatic `{ Workspace: "name" }` arg
1911
- * resolution does not apply.
1912
- *
1913
- * @throws {InvalidArgumentError} if no workspace variable with that name has been defined.
1914
- */
1915
- resolveWorkspaceOffsetId(name: string): WorkspaceOffsetId;
1916
- buildUnsignedTransaction(): UnsignedTransactionV1;
1917
- private addNamedId;
1918
- private requireNamedId;
1919
- private getOffsetIdFromWorkspaceName;
1920
- private resolveArgs;
1921
- }
1922
-
1923
- export { TransactionEnvelope }
1924
-
1925
- /**
1926
- * The classified result of a finalized transaction.
1927
- *
1928
- * - `"Commit"` — all instructions committed successfully.
1929
- * - `"FeeIntentCommit"` — fee instructions committed but execution was aborted
1930
- * (the network accepted the fee intent but rejected the rest).
1931
- * - `"Reject"` — the entire transaction was rejected.
1932
- */
1933
- export declare interface TransactionOutcome {
1934
- outcome: FinalizeOutcome | "Reject";
1935
- reason?: string;
1936
- }
1937
-
1938
- /**
1939
- * Raised when consensus rejects a transaction.
1940
- *
1941
- * `txId` is the rejected transaction's identifier; `reason` is the human-readable
1942
- * reason (the indexer's `abort_details` string or a `JSON.stringify` of the abort
1943
- * variant when no string was supplied). `rejectReason` is the structured engine
1944
- * reject reason if available — currently optional because the indexer's
1945
- * `Decision.Abort` carries the lighter `AbortReason` shape, not the full
1946
- * `RejectReason`. Callers should branch on `reason` (string) for most cases.
1947
- */
1948
- export declare class TransactionRejectedError extends OotleError {
1949
- readonly txId: string;
1950
- readonly reason: string;
1951
- readonly rejectReason?: RejectReason;
1952
- constructor(message: string, options: ErrorOptions & {
1953
- txId: string;
1954
- reason: string;
1955
- rejectReason?: RejectReason;
1956
- });
1957
- }
1958
-
1959
- export { TransactionSignature }
1960
-
1961
- /** Raised when polling / SSE both timed out before the transaction finalized. */
1962
- export declare class TransactionTimeoutError extends OotleError {
1963
- readonly txId: string;
1964
- constructor(message: string, options: ErrorOptions & {
1965
- txId: string;
1966
- });
1967
- }
1968
-
1969
- export { TransactionV1 }
1970
-
1971
- export { UnsealedTransactionV1 }
1972
-
1973
- export { UnsignedTransactionV1 }
1974
-
1975
- /**
1976
- * `UnsignedTransactionV1` with the `blobs` list: standard-base64 payloads
1977
- * referenced from instructions by index (see {@link TransactionBuilder.publishTemplate}).
1978
- *
1979
- * @deprecated `blobs` is now a field of `UnsignedTransactionV1` itself (ootle-ts-bindings
1980
- * ≥ 1.47), so this intersection adds nothing. Kept as an alias for one release; use
1981
- * `UnsignedTransactionV1` directly.
1982
- */
1983
- export declare type UnsignedTransactionWithBlobs = UnsignedTransactionV1;
1984
-
1985
- /**
1986
- * CBOR-encode a `UtxoAddress` as `Tag(141, [ResourceAddress, UtxoId])`, where the
1987
- * `UtxoId` is the 32-byte commitment byte string.
1988
- *
1989
- * @throws {InvalidArgumentError} if the resource address or id is not 32 bytes.
1990
- */
1991
- export declare function utxoAddressLiteral(address: UtxoAddress): InstructionArg;
1992
-
1993
- /**
1994
- * CBOR-encode a `ValidatorFeePoolAddress` as `Tag(138, bytes(32))`. Accepts
1995
- * either the `vnfp_<hex>` form or the bare 64-hex-char tail.
1996
- *
1997
- * @throws {InvalidArgumentError} if the address body is not 32 bytes (64 hex chars).
1998
- */
1999
- export declare function validatorFeePoolAddressLiteral(address: ValidatorFeePoolAddress): InstructionArg;
2000
-
2001
- /**
2002
- * CBOR-encode a `VaultId` as `Tag(132, bytes(32))`. Accepts either the
2003
- * `vault_<hex>` form or the bare 64-hex-char tail.
2004
- *
2005
- * @throws {InvalidArgumentError} if the address body is not 32 bytes (64 hex chars).
2006
- */
2007
- export declare function vaultIdLiteral(address: VaultId): InstructionArg;
2008
-
2009
- /** Base class for errors raised by {@link OotleWallet} operations. */
2010
- export declare class WalletError extends OotleError {
2011
- }
2012
-
2013
- /**
2014
- * Authorizes a {@link StealthTransferSpec} produced by {@link StealthTransfer}: unblinds any
2015
- * stealth inputs, signs the balance proof, hydrates + patches the statement, then returns an
2016
- * {@link AuthorizedTransfer} that produces one-time spend-key authorizations and seals the
2017
- * envelope. Handles both the revealed-only path and the full stealth-input spend path.
2018
- */
2019
- export declare class WalletStealthAuthorizer {
2020
- private readonly wallet;
2021
- private readonly spec;
2022
- private readonly crypto;
2023
- private readonly mustSignWithAccountKey;
2024
- private readonly viewSecret?;
2025
- private constructor();
2026
- /**
2027
- * Build an authorizer from a builder spec.
2028
- *
2029
- * @param wallet - The multi-signer wallet (supplies the account-key + one-time signatures).
2030
- * @param spec - The spec from {@link StealthTransfer.prepare}.
2031
- * @param options - Optional `viewSecret`, account-signature toggle, crypto seam.
2032
- */
2033
- static fromSpec(wallet: OotleWallet, spec: StealthTransferSpec, options?: WalletStealthAuthorizerOptions): WalletStealthAuthorizer;
2034
- /**
2035
- * Hydrate + sign the transfer:
2036
- * 1. resolve each stealth input — fetch its UTXO, unblind it to recover the mask, and
2037
- * remember the sender public nonce (revealed-only → no inputs, no fetch);
2038
- * 2. aggregate the input masks (`Mask.zero()` when there are no stealth inputs);
2039
- * 3. sign the balance proof over the (already-canonical) inputs/outputs statement JSONs;
2040
- * 4. build the complete (hydrated) statement and pre-flight `validateTransfer`;
2041
- * 5. patch the unsigned tx's sole stealth instruction with the hydrated statement.
2042
- *
2043
- * Returns an {@link AuthorizedTransfer} that owns the hydrated state and can produce
2044
- * one-time spend-key authorizations or seal the envelope. The authorizer is not mutated.
2045
- *
2046
- * @param provider - Read-only chain access (fetches the input UTXOs).
2047
- */
2048
- prepare(provider: Provider): Promise<AuthorizedTransfer>;
2049
- /**
2050
- * Resolve the view secret used to unblind stealth inputs: prefer the explicit one passed
2051
- * to {@link fromSpec}; else fall back to the wallet's default signer `getViewSecret?.()`.
2052
- *
2053
- * @throws {WalletError} a clear, actionable error when neither is available **and**
2054
- * there are stealth inputs to unblind (the revealed-only path never needs it).
2055
- */
2056
- private resolveViewSecret;
2057
- /** The wallet's default signer address, or `""` if none is set (so view-secret resolution fails clearly). */
2058
- private safeDefaultAddress;
2059
- /**
2060
- * Fetch + unblind each stealth input, in `spec.inputs` order.
2061
- *
2062
- * For each input: `getStealthUtxo` → `parseSubstateUtxo` (commitment + body) →
2063
- * `decryptInputData(..., { senderPublicNonce, viewSecret, skipMemo: true })` to recover
2064
- * the mask. The sender public nonce is read from the **fetched UTXO body**, not the spec
2065
- * (the spec only carries the commitment), and kept for one-time signing.
2066
- *
2067
- * `skipMemo: true` — spending only needs the mask + value, not the memo (vs the
2068
- * receive-side `decryptOwnedUtxo`, which decrypts the memo).
2069
- */
2070
- private resolveStealthInputs;
2071
- }
2072
-
2073
- /** Options for {@link WalletStealthAuthorizer.fromSpec}. */
2074
- export declare interface WalletStealthAuthorizerOptions {
2075
- /**
2076
- * The owner/recipient 32-byte view secret, needed to unblind stealth inputs. **Optional**:
2077
- * the revealed-only path never uses it; for stealth-input transfers it is taken here first,
2078
- * else falls back to the wallet's default signer `getViewSecret?.()` (only `SecretKeyWallet`
2079
- * supplies one). If neither is available and there are stealth inputs, `prepare` throws.
2080
- */
2081
- viewSecret?: Uint8Array;
2082
- /**
2083
- * Whether to append the account-key Schnorr signature when sealing. Defaults to `true`.
2084
- * Set `false` to omit it (e.g. the account already authorized out-of-band).
2085
- */
2086
- mustSignWithAccountKey?: boolean;
2087
- /**
2088
- * Injectable crypto seam; defaults to {@link WasmStealthCrypto}. Tests pass a
2089
- * {@link FakeStealthCrypto}.
2090
- */
2091
- crypto?: StealthCryptoProvider;
2092
- }
2093
-
2094
- /**
2095
- * The real `StealthCryptoProvider`, backed by `@tari-project/ootle-wasm@0.38.0`.
2096
- *
2097
- * Marshals between the step-02 domain types (`Mask`, `Output`, statements) and the raw
2098
- * WASM ABI (snake_case result fields, positional args, raw `Uint8Array`s/`bigint`s).
2099
- * Async signatures wrap synchronous WASM calls — see {@link StealthCryptoProvider}.
2100
- */
2101
- export declare class WasmStealthCrypto implements StealthCryptoProvider {
2102
- /**
2103
- * The network byte fed to the WASM output-witness and DH calls. Defaults to
2104
- * {@link Network.LocalNet}; pass the target network for non-local transfers.
2105
- */
2106
- private readonly network;
2107
- constructor(network?: Network);
2108
- generateOutputsStatement(specs: Output[], revealedOutputAmount: bigint, revealedReceiver?: Uint8Array): Promise<{
2109
- statement: StealthOutputsStatement;
2110
- outputMask: Mask;
2111
- }>;
2112
- /** Build a single output witness JSON via WASM, mapping an {@link Output} spec. */
2113
- private outputWitness;
2114
- buildInputsStatement(inputs: StealthInput[], revealedAmount: bigint): Promise<StealthInputsStatement>;
2115
- generateBalanceProofSignature(inputMask: Mask, outputMask: Mask, inputsStatementJson: string, outputsStatementJson: string): Promise<BalanceProofSignature>;
2116
- validateBalanceProofSignature(proof: BalanceProofSignature, inputsStatementJson: string, outputsStatementJson: string): Promise<boolean>;
2117
- deriveAeadKey(privateKey: Uint8Array, publicKey: Uint8Array): Promise<Uint8Array>;
2118
- unblindOutput(commitment: Uint8Array, encryptedData: Uint8Array, aeadKey: Uint8Array, skipMemo: boolean): Promise<DecryptedData>;
2119
- aggregateInputMasks(masks: Mask[]): Promise<Mask>;
2120
- stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
2121
- validateTransfer(statement: StealthTransferStatement): Promise<void>;
2122
- }
2123
-
2124
- export declare interface WatchOptions {
2125
- /** How often to poll for the transaction result, in milliseconds. Defaults to 500ms. */
2126
- pollIntervalMs?: number;
2127
- /** Maximum time to wait before throwing a timeout error, in milliseconds. Defaults to 60000ms. */
2128
- timeoutMs?: number;
2129
- }
2130
-
2131
- /**
2132
- * Polls the provider until a transaction reaches a finalized state, then returns the result.
2133
- *
2134
- * Throws for `Reject` outcomes. `FeeIntentCommit` (fees paid, execution aborted) also
2135
- * throws with a distinct message so callers can distinguish it from a full rejection.
2136
- * Use `classifyOutcome` on the raw result for non-throwing outcome inspection.
2137
- *
2138
- * @throws {TransactionRejectedError} when consensus rejects the transaction, or commits
2139
- * only the fee intent (execution aborted). The error's `.txId` and `.reason` carry the
2140
- * structured fields; the message remains the human-readable summary.
2141
- * @throws {TransactionTimeoutError} when the transaction did not finalize within
2142
- * `timeoutMs`. The error's `.txId` identifies the polled transaction.
2143
- */
2144
- export declare function watchTransaction(provider: Provider, txId: string, opts?: WatchOptions): Promise<IndexerGetTransactionResultResponse>;
2145
-
2146
- /** Claim resource held by the XTR faucet (object key `[1, 2, 3, 0, …, 0, 2]`). */
2147
- export declare const XTR_FAUCET_CLAIM_RESOURCE_ADDRESS = "resource_0102030000000000000000000000000000000000000000000000000000000002";
2148
-
2149
- /**
2150
- * On-chain XTR faucet component address (object key `[1, 2, 3, 0, …, 0]`).
2151
- * LocalNet scripts call this via `FaucetInvokeBuilder` to claim revealed TARI funds.
2152
- */
2153
- export declare const XTR_FAUCET_COMPONENT_ADDRESS = "component_0102030000000000000000000000000000000000000000000000000000000000";
2154
-
2155
- /** Vault held by the XTR faucet (object key `[1, 2, 3, 0, …, 0, 1]`). */
2156
- export declare const XTR_FAUCET_VAULT_ADDRESS = "vault_0102030000000000000000000000000000000000000000000000000000000001";
2157
-
2158
- export { }