@tari-project/ootle 0.2.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 +98 -10
  2. package/dist/index.js +411 -378
  3. package/package.json +3 -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.
@@ -86,8 +86,13 @@ export declare class AccountInvokeBuilder {
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
  */
@@ -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`.
@@ -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
  /**
@@ -1678,8 +1738,18 @@ export declare class TransactionBuilder {
1678
1738
  private unsignedTransaction;
1679
1739
  private workspaceIds;
1680
1740
  private feeWorkspaceIds;
1681
- constructor(network: Network | number);
1682
- static new(network: Network | number): TransactionBuilder;
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`
@@ -1737,8 +1807,26 @@ export declare class TransactionBuilder {
1737
1807
  withFeeInstructionsBuilder(builder: (b: TransactionBuilder) => TransactionBuilder): this;
1738
1808
  addInput(input: SubstateRequirement): this;
1739
1809
  withInputs(inputs: SubstateRequirement[]): this;
1810
+ /** @throws {InvalidArgumentError} if `minEpoch` is not a non-negative integer. */
1740
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
+ */
1741
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;
1742
1830
  /**
1743
1831
  * Adopt an existing transaction and keep building on it.
1744
1832
  *