@tari-project/ootle 0.2.0 → 0.4.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.
- package/dist/index.d.ts +98 -10
- package/dist/index.js +411 -378
- 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)
|
|
90
|
-
*
|
|
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}
|
|
570
|
-
*
|
|
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
|
-
|
|
1682
|
-
|
|
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
|
*
|