@tari-project/ootle 0.1.0 → 0.3.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 (3) hide show
  1. package/dist/index.d.ts +132 -20
  2. package/dist/index.js +312 -239
  3. package/package.json +11 -3
package/dist/index.d.ts CHANGED
@@ -48,7 +48,7 @@ import { WorkspaceOffsetId } from '@tari-project/ootle-ts-bindings';
48
48
  *
49
49
  * @example
50
50
  * ```ts
51
- * const tx = new AccountInvokeBuilder(network)
51
+ * const tx = new AccountInvokeBuilder(network, maxEpoch)
52
52
  * .feeTransactionPayFromComponent(accountAddress, 1000n)
53
53
  * .publicTransfer(accountAddress, resourceAddress, 500n, recipientAddress)
54
54
  * .build();
@@ -56,7 +56,7 @@ import { WorkspaceOffsetId } from '@tari-project/ootle-ts-bindings';
56
56
  */
57
57
  export declare class AccountInvokeBuilder {
58
58
  private builder;
59
- constructor(network: Network | number);
59
+ constructor(network: Network | number, maxEpoch: number);
60
60
  /**
61
61
  * Declares the transaction's substate inputs (e.g. the source account and its
62
62
  * vaults) so the indexer resolves their versions before submission.
@@ -80,14 +80,19 @@ export declare class AccountInvokeBuilder {
80
80
  * for a follow-up instruction.
81
81
  */
82
82
  publishTemplate(_sourceAccount: ComponentAddress, templateBinaryBase64: string, workspaceBucket?: string): this;
83
- build(): UnsignedTransactionWithBlobs;
83
+ build(): UnsignedTransactionV1;
84
84
  }
85
85
 
86
86
  export { Amount }
87
87
 
88
88
  /**
89
- * CBOR-encode an `Amount` (u128) as the `[lo_u64, hi_u64]` pair the runtime
90
- * deserialises via `tari_bor`.
89
+ * CBOR-encode an `Amount` (u128) the way the runtime's `minicbor` codec does:
90
+ * a plain CBOR unsigned integer while the value fits the CBOR integer range
91
+ * (`0..=u64::MAX`), and an RFC 8949 tag-2 unsigned bignum (minimal-length
92
+ * big-endian byte string) above it.
93
+ *
94
+ * Wire-breaking against the pre-0.39 `[lo_u64, hi_u64]` digit-array form —
95
+ * templates built against an older `tari_template_lib` cannot decode this.
91
96
  *
92
97
  * @throws {InvalidArgumentError} if `value` is negative or overflows u128.
93
98
  */
@@ -351,7 +356,7 @@ export { Decision }
351
356
  * The result of decrypting an owned output via the AEAD path (`unblindOutput`).
352
357
  *
353
358
  * Maps from the WASM `DecryptedOutputResult { mask: Uint8Array, value: bigint,
354
- * memo_json: string | undefined }`. Per the verified 0.32 ABI, `memo` is the
359
+ * memo_json: string | undefined }`. Per the verified 0.38 ABI, `memo` is the
355
360
  * **JSON-encoded `Memo` string** (`U256` / `Message` / `Bytes` / `PayRefAndBytes`),
356
361
  * not raw bytes — callers parse it if needed.
357
362
  */
@@ -406,6 +411,14 @@ export declare interface DecryptInputOptions {
406
411
  */
407
412
  export declare function decryptOwnedUtxo(crypto: StealthCryptoProvider, viewSecret: Uint8Array, substate: IndexerGetSubstateResponse, substateId: string): Promise<DecryptedData | null>;
408
413
 
414
+ /**
415
+ * The validity window {@link resolveMaxEpoch} applies when the caller does not name one.
416
+ * Ten epochs is comfortably longer than a transaction takes to finalize while still
417
+ * letting a stuck transaction die on its own rather than lingering as a resubmittable
418
+ * intent.
419
+ */
420
+ export declare const DEFAULT_TRANSACTION_VALIDITY_EPOCHS = 10;
421
+
409
422
  /**
410
423
  * Returns a known default indexer URL for the given network.
411
424
  * Mirrors `default_indexer_url()` from the Rust ootle-rs crate.
@@ -442,7 +455,7 @@ export { ExecuteResult }
442
455
  *
443
456
  * @example
444
457
  * ```ts
445
- * const tx = new FaucetInvokeBuilder(network, faucetAddress)
458
+ * const tx = new FaucetInvokeBuilder(network, maxEpoch, faucetAddress)
446
459
  * .feeTransactionPayFromComponent(accountAddress, 1000n)
447
460
  * .takeFaucetFunds(accountAddress, 10_000n)
448
461
  * .build();
@@ -451,7 +464,7 @@ export { ExecuteResult }
451
464
  export declare class FaucetInvokeBuilder {
452
465
  private builder;
453
466
  private readonly faucetAddress;
454
- constructor(network: Network | number, faucetAddress: ComponentAddress);
467
+ constructor(network: Network | number, maxEpoch: number, faucetAddress: ComponentAddress);
455
468
  feeTransactionPayFromComponent(componentAddress: ComponentAddress, maxFee: bigint): this;
456
469
  /**
457
470
  * Takes `amount` of funds from the faucet and deposits them into `destinationAccount`.
@@ -468,7 +481,7 @@ export declare class FaucetInvokeBuilder {
468
481
  * Mirrors `FaucetInvokeBuilder::publish_template` from ootle-rs.
469
482
  */
470
483
  publishTemplate(templateAddress: PublishedTemplateAddress, workspaceBucket?: string): this;
471
- build(): UnsignedTransactionWithBlobs;
484
+ build(): UnsignedTransactionV1;
472
485
  }
473
486
 
474
487
  export { FinalizeOutcome }
@@ -566,8 +579,8 @@ export { InstructionArg }
566
579
 
567
580
  /**
568
581
  * CBOR-encode a plain integer (Rust `u8`…`u128` / `i8`…`i128`) as a bare CBOR
569
- * integer. Distinct from {@link amountLiteral}, which encodes the `Amount` type
570
- * as a two-element array.
582
+ * integer. Distinct from {@link amountLiteral} only above the CBOR integer
583
+ * range, where an `Amount` becomes a tag-2 bignum and this throws instead.
571
584
  *
572
585
  * @throws {InvalidArgumentError} if the magnitude exceeds the 64-bit CBOR
573
586
  * integer range (128-bit bignum encoding is not supported).
@@ -635,6 +648,14 @@ export declare class Mask extends Bytes32 {
635
648
  static fromHex(hex: string): Mask;
636
649
  }
637
650
 
651
+ /**
652
+ * The longest validity window any network accepts, in epochs
653
+ * (`ConsensusConstants::max_transaction_validity_epochs`, ~30 days). A transaction whose
654
+ * `max_epoch` sits further ahead of the current epoch than this is aborted with
655
+ * `AbortReason::ValidityWindowTooLong`.
656
+ */
657
+ export declare const MAX_TRANSACTION_VALIDITY_EPOCHS = 2160;
658
+
638
659
  /**
639
660
  * CBOR-encode a `Metadata` map as `Tag(129, Map<text, text>)`. Keys are emitted
640
661
  * sorted to match the runtime's `BTreeMap` ordering.
@@ -880,6 +901,15 @@ export declare function patchStealthStatement(unsignedTx: UnsignedTransactionV1,
880
901
  export declare interface Provider {
881
902
  /** Returns the network this provider is connected to. */
882
903
  network(): Network;
904
+ /**
905
+ * Returns the epoch the network is currently on.
906
+ *
907
+ * Every transaction carries a mandatory `max_epoch`, capped at
908
+ * `MAX_TRANSACTION_VALIDITY_EPOCHS` past this value, so a builder needs the chain tip
909
+ * before it can be constructed: `TransactionBuilder.new(network, await
910
+ * provider.getCurrentEpoch() + 10)`.
911
+ */
912
+ getCurrentEpoch(): Promise<number>;
883
913
  /** Fetches a single substate by ID and optional version. */
884
914
  getSubstate(substateId: string, version?: number | null): Promise<IndexerGetSubstateResponse>;
885
915
  /**
@@ -935,6 +965,20 @@ declare interface ResolvedStealthInput {
935
965
  publicNonce: Uint8Array;
936
966
  }
937
967
 
968
+ /**
969
+ * Reads the chain tip and returns the `max_epoch` a transaction built now should carry:
970
+ * `currentEpoch + leadEpochs`.
971
+ *
972
+ * ```ts
973
+ * const builder = TransactionBuilder.new(provider.network(), await resolveMaxEpoch(provider));
974
+ * ```
975
+ *
976
+ * @throws {InvalidArgumentError} if `leadEpochs` is not a positive integer, or exceeds
977
+ * {@link MAX_TRANSACTION_VALIDITY_EPOCHS} (which the network would reject with
978
+ * `AbortReason::ValidityWindowTooLong`).
979
+ */
980
+ export declare function resolveMaxEpoch(provider: Provider, leadEpochs?: number): Promise<number>;
981
+
938
982
  /**
939
983
  * Resolves unversioned inputs in the unsigned transaction by fetching their current
940
984
  * version from the provider.
@@ -992,6 +1036,12 @@ export declare function sendTransaction(provider: Provider, signers: Signer | Si
992
1036
  * losslessly. We therefore stringify each carrier as a unique placeholder, then splice the raw
993
1037
  * fragment in place of the quoted placeholder, never round-tripping the amounts through a JS
994
1038
  * number.
1039
+ *
1040
+ * Any `bigint` field (e.g. a large `nonce`) is emitted as a decimal *string*, matching the
1041
+ * Tari clients' wire encoding: every 64-bit field on these APIs accepts a string as well as a
1042
+ * number, and a string is the only lossless encoding above `Number.MAX_SAFE_INTEGER`. Plain
1043
+ * `JSON.stringify` throws on a `bigint`, and the global `BigInt.prototype.toJSON` patch the
1044
+ * client packages used to install was removed in 0.39.
995
1045
  */
996
1046
  export declare function serializeUnsignedTx(unsignedTx: UnsignedTransactionV1): string;
997
1047
 
@@ -1308,6 +1358,8 @@ export declare class StealthTransfer {
1308
1358
  private readonly crypto;
1309
1359
  private builder;
1310
1360
  private readonly state;
1361
+ /** Set by {@link withMaxEpoch}; `null` means {@link prepare} resolves one from the chain tip. */
1362
+ private maxEpoch;
1311
1363
  /** Guards against a second {@link prepare} re-emitting instructions into the same builder. */
1312
1364
  private prepared;
1313
1365
  /**
@@ -1341,6 +1393,14 @@ export declare class StealthTransfer {
1341
1393
  * @throws {InvalidArgumentError} if no source account is set, or `amount` is not `> 0`.
1342
1394
  */
1343
1395
  payFeeFromRevealed(amount: bigint): this;
1396
+ /**
1397
+ * Set the transaction's validity window explicitly. Without this, {@link prepare}
1398
+ * reads the current epoch from the provider and applies
1399
+ * `DEFAULT_TRANSACTION_VALIDITY_EPOCHS`.
1400
+ *
1401
+ * @throws {InvalidArgumentError} if `maxEpoch` is not a non-negative integer.
1402
+ */
1403
+ withMaxEpoch(maxEpoch: number): this;
1344
1404
  /** Escape hatch over the inner {@link TransactionBuilder} (e.g. extra instructions). */
1345
1405
  withBuilder(fn: (b: TransactionBuilder) => TransactionBuilder): this;
1346
1406
  /**
@@ -1676,10 +1736,20 @@ export declare interface TransactionAuthorization {
1676
1736
  */
1677
1737
  export declare class TransactionBuilder {
1678
1738
  private unsignedTransaction;
1679
- private allocatedIds;
1680
- private currentId;
1681
- constructor(network: Network | number);
1682
- static new(network: Network | number): TransactionBuilder;
1739
+ private workspaceIds;
1740
+ private feeWorkspaceIds;
1741
+ /**
1742
+ * `maxEpoch` is required: every transaction now carries a bounded validity window
1743
+ * (`UnsignedTransactionV1.max_epoch`), so the last epoch in which it may be sequenced
1744
+ * is decided up front rather than left open. The network rejects a window longer than
1745
+ * {@link MAX_TRANSACTION_VALIDITY_EPOCHS} epochs past the current one with
1746
+ * `AbortReason::ValidityWindowTooLong`, so derive it from the chain tip — e.g.
1747
+ * `(await provider.getCurrentEpoch()) + 10`.
1748
+ *
1749
+ * @throws {InvalidArgumentError} if `maxEpoch` is not a non-negative integer.
1750
+ */
1751
+ constructor(network: Network | number, maxEpoch: number);
1752
+ static new(network: Network | number, maxEpoch: number): TransactionBuilder;
1683
1753
  callFunction<T extends TariFunctionDefinition>(func: T, args: Exclude<T["args"], undefined>): this;
1684
1754
  /**
1685
1755
  * @throws {InvalidArgumentError} if `method` provides neither `componentAddress`
@@ -1722,11 +1792,51 @@ export declare class TransactionBuilder {
1722
1792
  addFeeInstruction(instruction: Instruction): this;
1723
1793
  withInstructions(instructions: Instruction[]): this;
1724
1794
  withFeeInstructions(instructions: Instruction[]): this;
1795
+ /**
1796
+ * Account for slots claimed by instructions the builder did not allocate itself, so a
1797
+ * later `saveVar` cannot re-issue one. Rust does this inline in `add_instruction`.
1798
+ */
1799
+ private observeAllocations;
1800
+ /**
1801
+ * Build the fee instructions with a nested builder, mirroring the Rust builder's separate
1802
+ * fee-instruction builder. The nested builder gets its own workspace scope — correct,
1803
+ * because the engine clears the workspace between the fee and main instruction runs.
1804
+ *
1805
+ * Note this REPLACES any fee instructions already set, as it always has.
1806
+ */
1725
1807
  withFeeInstructionsBuilder(builder: (b: TransactionBuilder) => TransactionBuilder): this;
1726
1808
  addInput(input: SubstateRequirement): this;
1727
1809
  withInputs(inputs: SubstateRequirement[]): this;
1810
+ /** @throws {InvalidArgumentError} if `minEpoch` is not a non-negative integer. */
1728
1811
  withMinEpoch(minEpoch: number): this;
1812
+ /**
1813
+ * Overrides the validity window set at construction. See the constructor for the
1814
+ * network's cap on how far ahead of the current epoch this may sit.
1815
+ *
1816
+ * @throws {InvalidArgumentError} if `maxEpoch` is not a non-negative integer.
1817
+ */
1729
1818
  withMaxEpoch(maxEpoch: number): this;
1819
+ /**
1820
+ * Stamps the transaction nonce, which distinguishes otherwise-identical transactions.
1821
+ *
1822
+ * The transaction id excludes the seal signature's witness data, so two identical
1823
+ * bodies sealed by the same key are the *same* transaction — submitting both executes
1824
+ * once. Give each intent a distinct nonce when repeated submissions must each execute.
1825
+ * Defaults to `0`.
1826
+ *
1827
+ * @throws {InvalidArgumentError} if `nonce` is negative or overflows u64.
1828
+ */
1829
+ withNonce(nonce: number | bigint): this;
1830
+ /**
1831
+ * Adopt an existing transaction and keep building on it.
1832
+ *
1833
+ * The adopted transaction is **copied**, not aliased: subsequent builder calls must not
1834
+ * reach back into the caller's object. The manual co-signing flow ships
1835
+ * `JSON.stringify(unsigned)` across a boundary, so mutating a transaction the caller has
1836
+ * already serialized or signed makes the two sides disagree — surfacing only at submit
1837
+ * time as the opaque engine error `"Transaction has one or more invalid signature(s)"`.
1838
+ * This mirrors the copy {@link buildUnsignedTransaction} makes on the way out.
1839
+ */
1730
1840
  withUnsignedTransaction(unsignedTransaction: UnsignedTransactionV1): this;
1731
1841
  /**
1732
1842
  * Resolves a workspace variable name (supporting dot-notation offsets, e.g. `"bucket.0"`)
@@ -1739,7 +1849,7 @@ export declare class TransactionBuilder {
1739
1849
  * @throws {InvalidArgumentError} if no workspace variable with that name has been defined.
1740
1850
  */
1741
1851
  resolveWorkspaceOffsetId(name: string): WorkspaceOffsetId;
1742
- buildUnsignedTransaction(): UnsignedTransactionWithBlobs;
1852
+ buildUnsignedTransaction(): UnsignedTransactionV1;
1743
1853
  private addNamedId;
1744
1854
  private requireNamedId;
1745
1855
  private getOffsetIdFromWorkspaceName;
@@ -1801,10 +1911,12 @@ export { UnsignedTransactionV1 }
1801
1911
  /**
1802
1912
  * `UnsignedTransactionV1` with the `blobs` list: standard-base64 payloads
1803
1913
  * referenced from instructions by index (see {@link TransactionBuilder.publishTemplate}).
1914
+ *
1915
+ * @deprecated `blobs` is now a field of `UnsignedTransactionV1` itself (ootle-ts-bindings
1916
+ * ≥ 1.47), so this intersection adds nothing. Kept as an alias for one release; use
1917
+ * `UnsignedTransactionV1` directly.
1804
1918
  */
1805
- export declare type UnsignedTransactionWithBlobs = UnsignedTransactionV1 & {
1806
- blobs: string[];
1807
- };
1919
+ export declare type UnsignedTransactionWithBlobs = UnsignedTransactionV1;
1808
1920
 
1809
1921
  /**
1810
1922
  * CBOR-encode a `UtxoAddress` as `Tag(141, [ResourceAddress, UtxoId])`, where the
@@ -1916,7 +2028,7 @@ export declare interface WalletStealthAuthorizerOptions {
1916
2028
  }
1917
2029
 
1918
2030
  /**
1919
- * The real `StealthCryptoProvider`, backed by `@tari-project/ootle-wasm@0.32.0`.
2031
+ * The real `StealthCryptoProvider`, backed by `@tari-project/ootle-wasm@0.38.0`.
1920
2032
  *
1921
2033
  * Marshals between the step-02 domain types (`Mask`, `Output`, statements) and the raw
1922
2034
  * WASM ABI (snake_case result fields, positional args, raw `Uint8Array`s/`bigint`s).