@tari-project/ootle 0.17.0 → 0.19.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 +138 -11
  2. package/dist/index.js +521 -444
  3. package/package.json +4 -4
package/dist/index.d.ts CHANGED
@@ -1,11 +1,13 @@
1
1
  import { AllocatableAddressType } from '@tari-project/ootle-ts-bindings';
2
2
  import { Amount } from '@tari-project/ootle-ts-bindings';
3
3
  import { ClaimedOutputTombstoneAddress } from '@tari-project/ootle-ts-bindings';
4
+ import { ComponentAccessRules } from '@tari-project/ootle-ts-bindings';
4
5
  import { ComponentAddress } from '@tari-project/ootle-ts-bindings';
5
6
  import { ConfidentialWithdrawProof } from '@tari-project/ootle-ts-bindings';
6
7
  import { Decision } from '@tari-project/ootle-ts-bindings';
7
8
  import { Event as Event_2 } from '@tari-project/ootle-ts-bindings';
8
9
  import { ExecuteResult } from '@tari-project/ootle-ts-bindings';
10
+ import { FeeReceipt } from '@tari-project/ootle-ts-bindings';
9
11
  import { FinalizeOutcome } from '@tari-project/ootle-ts-bindings';
10
12
  import { FinalizeResult } from '@tari-project/ootle-ts-bindings';
11
13
  import { GetSubstatesRequest } from '@tari-project/ootle-ts-bindings';
@@ -26,18 +28,22 @@ import { MainSigner } from '@tari-project/ootle-ts-bindings';
26
28
  import { MinotariBurnClaimProof } from '@tari-project/ootle-ts-bindings';
27
29
  import { NonFungibleAddress } from '@tari-project/ootle-ts-bindings';
28
30
  import { OutputBody } from '@tari-project/ootle-ts-bindings';
31
+ import { OwnerRule } from '@tari-project/ootle-ts-bindings';
29
32
  import { PublishedTemplateAddress } from '@tari-project/ootle-ts-bindings';
30
33
  import { RejectReason } from '@tari-project/ootle-ts-bindings';
31
34
  import { Resource } from '@tari-project/ootle-ts-bindings';
32
35
  import { ResourceAddress } from '@tari-project/ootle-ts-bindings';
33
36
  import { RistrettoPublicKeyBytes } from '@tari-project/ootle-ts-bindings';
37
+ import { SpendAuthorization } from '@tari-project/ootle-ts-bindings';
34
38
  import { StealthTransferStatement as StealthTransferStatement_2 } from '@tari-project/ootle-ts-bindings';
35
39
  import { SubstateId } from '@tari-project/ootle-ts-bindings';
36
40
  import { SubstateRequirement } from '@tari-project/ootle-ts-bindings';
37
41
  import { SubstateValue } from '@tari-project/ootle-ts-bindings';
38
42
  import { Transaction } from '@tari-project/ootle-ts-bindings';
43
+ import { transactionBody } from '@tari-project/ootle-ts-bindings';
39
44
  import { TransactionEnvelope } from '@tari-project/ootle-ts-bindings';
40
45
  import { TransactionReceipt } from '@tari-project/ootle-ts-bindings';
46
+ import { transactionSchemaVersion } from '@tari-project/ootle-ts-bindings';
41
47
  import { TransactionSignature } from '@tari-project/ootle-ts-bindings';
42
48
  import { TransactionV1 } from '@tari-project/ootle-ts-bindings';
43
49
  import { UnsealedTransactionV1 } from '@tari-project/ootle-ts-bindings';
@@ -146,6 +152,10 @@ export declare class AuthorizedTransfer {
146
152
  private readonly sealKeypair;
147
153
  /** Extra signatures appended via {@link addSignature} before sealing. */
148
154
  private readonly extraSignatures;
155
+ /** Co-signer keys declared via {@link addAuthorizer}, before the authorizer set is fixed. */
156
+ private readonly coSignerKeys;
157
+ /** The authorizer set, fixed on first use by {@link getAuthorizerPublicKeys}. */
158
+ private authorizerSet?;
149
159
  /**
150
160
  * Memoized one-time spend-key authorizations — see {@link createAuthorizations} for the
151
161
  * lifecycle and why memoization (not recomputation) is required.
@@ -154,6 +164,23 @@ export declare class AuthorizedTransfer {
154
164
  constructor(params: AuthorizedTransferParams);
155
165
  /** The shared seal signer public key (fixed for this transfer's lifetime). */
156
166
  getSealPublicKey(): Uint8Array;
167
+ /**
168
+ * Declare an external co-signer's public key as an authorizer of this transfer.
169
+ *
170
+ * Every signature commits to the whole authorizer set, so a co-signer must be declared before
171
+ * the set is fixed — that is, before {@link getAuthorizerPublicKeys}, {@link createAuthorizations}
172
+ * or {@link seal} is first called. The co-signer then signs over {@link getAuthorizerPublicKeys}
173
+ * and its signature is handed back via {@link addSignature}.
174
+ *
175
+ * @throws {WalletError} if the authorizer set is already fixed.
176
+ */
177
+ addAuthorizer(publicKey: Uint8Array): this;
178
+ /**
179
+ * The transfer's authorizer set: the account key (unless `mustSignWithAccountKey` is `false`),
180
+ * each stealth input's one-time spend key, and every co-signer declared via
181
+ * {@link addAuthorizer}, in canonical order. Fixed on the first call.
182
+ */
183
+ getAuthorizerPublicKeys(): Promise<Uint8Array[]>;
157
184
  /** The hydrated, post-`prepare` spec (balance proof filled, instruction patched). */
158
185
  getSpec(): StealthTransferSpec;
159
186
  /**
@@ -193,6 +220,9 @@ export declare class AuthorizedTransfer {
193
220
  * sealing. The account-key signature is added automatically at {@link seal} unless
194
221
  * `mustSignWithAccountKey` is `false`.
195
222
  *
223
+ * The co-signer's key must have been declared with {@link addAuthorizer}, and its signature made
224
+ * over {@link getAuthorizerPublicKeys}; {@link seal} throws `SignerError` otherwise.
225
+ *
196
226
  * Do **NOT** pass the per-input one-time spend-key authorizations here — they are
197
227
  * produced (memoized) by {@link createAuthorizations} and auto-included by {@link seal}
198
228
  * exactly once. Re-adding them via this method would double-count them in the sealed tx,
@@ -284,6 +314,14 @@ declare abstract class Bytes32 {
284
314
  /** CBOR-encode a `Vec<u8>` as a CBOR byte string. */
285
315
  export declare function bytesLiteral(value: Uint8Array): InstructionArg;
286
316
 
317
+ /**
318
+ * Orders authorizer public keys canonically: ascending by bytes, without repeats.
319
+ *
320
+ * Every 32-byte key is length-checked. This is the order the mempool requires of a schema V2
321
+ * transaction's authorizations (`AuthorizationsNotCanonical` otherwise).
322
+ */
323
+ export declare function canonicalAuthorizers(authorizers: Uint8Array[]): Uint8Array[];
324
+
287
325
  /**
288
326
  * CBOR-encode a `ClaimedOutputTombstoneAddress` as `Tag(136, bytes(32))`.
289
327
  * Accepts either the `tombstone_<hex>` form or the bare 64-hex-char tail.
@@ -303,6 +341,12 @@ export declare function classifyOutcome(result: IndexerTransactionFinalizedResul
303
341
  reason?: string;
304
342
  } | null;
305
343
 
344
+ /**
345
+ * The authorizer set of a transaction signed by `signers`: each signer's
346
+ * `getAuthorizerPublicKeys()`, or its `getPublicKey()` when it does not implement that.
347
+ */
348
+ export declare function collectAuthorizers(signers: Signer[]): Promise<Uint8Array[]>;
349
+
306
350
  /**
307
351
  * Extract the 32-byte commitment from a UTXO substate id.
308
352
  *
@@ -454,6 +498,13 @@ export declare function defaultIndexerUrl(network: Network): string;
454
498
  export declare class DefaultSignerNotSetError extends WalletError {
455
499
  }
456
500
 
501
+ /**
502
+ * Encodes an authorizer set for the WASM signing functions (`addTransactionSigner`,
503
+ * `attachTransactionSignature`, `hashUnsignedTransaction`): the 32-byte keys concatenated, in
504
+ * canonical order.
505
+ */
506
+ export declare function encodeAuthorizerSet(authorizers: Uint8Array[]): Uint8Array;
507
+
457
508
  /**
458
509
  * Opaque carrier for an output's ciphertext bytes (the AEAD-encrypted value/mask/memo
459
510
  * payload). Treated as opaque here: the stealth module never inspects the plaintext
@@ -470,6 +521,17 @@ export declare class EncryptedData {
470
521
  toHex(): string;
471
522
  }
472
523
 
524
+ /**
525
+ * The fee (µTari) to submit a dry-run transaction at: {@link feesCharged} plus
526
+ * {@link FEE_ESTIMATE_ALLOWANCE}, matching the engine's `FeeReceipt::required_fees`.
527
+ *
528
+ * The fee is itself an input to what a transaction is charged, so the real run of a transaction
529
+ * built at a different fee than its dry run meters slightly differently; the allowance covers that
530
+ * drift. It does not cover a different transaction: re-estimate after changing the inputs or
531
+ * outputs.
532
+ */
533
+ export declare function estimatedFee(receipt: Pick<FeeReceipt, "cost_breakdown">): bigint;
534
+
473
535
  export { ExecuteResult }
474
536
 
475
537
  /**
@@ -497,7 +559,7 @@ export declare class ExternalKeySigner implements Signer {
497
559
  constructor(options: ExternalKeySignerOptions);
498
560
  getAddress(): Promise<string>;
499
561
  getPublicKey(): Promise<Uint8Array>;
500
- signTransaction(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionSignature[]>;
562
+ signTransaction(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array, authorizers: Uint8Array[]): Promise<TransactionSignature[]>;
501
563
  }
502
564
 
503
565
  export declare interface ExternalKeySignerOptions {
@@ -555,6 +617,22 @@ export declare class FaucetInvokeBuilder {
555
617
  build(): UnsignedTransactionV1;
556
618
  }
557
619
 
620
+ /**
621
+ * µTari a dry-run fee estimate carries on top of what the dry run was charged.
622
+ *
623
+ * Mirrors `tari_engine_types::fees::FEE_ESTIMATE_ALLOWANCE`: the most a real run of the same
624
+ * transaction can cost over its dry run when built at a different fee.
625
+ */
626
+ export declare const FEE_ESTIMATE_ALLOWANCE = 12n;
627
+
628
+ /**
629
+ * The fee a receipt was charged (µTari): the sum of its cost breakdown, as the engine's
630
+ * `FeeReceipt::total_fees_charged` computes it.
631
+ *
632
+ * For a dry run this is what the run cost, not a fee to submit at: use {@link estimatedFee} for that.
633
+ */
634
+ export declare function feesCharged(receipt: Pick<FeeReceipt, "cost_breakdown">): bigint;
635
+
558
636
  export { FinalizeOutcome }
559
637
 
560
638
  export { FinalizeResult }
@@ -842,19 +920,31 @@ export declare class OotleWallet implements Signer {
842
920
  * @throws {DefaultSignerNotSetError} when no default signer is configured.
843
921
  * @throws {KeyProviderNotFoundError} when the default address has no registered provider.
844
922
  */
845
- signTransaction(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionSignature[]>;
923
+ signTransaction(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array, authorizers: Uint8Array[]): Promise<TransactionSignature[]>;
924
+ /**
925
+ * The default signer's authorizer keys.
926
+ *
927
+ * @throws {DefaultSignerNotSetError} when no default signer is configured.
928
+ * @throws {KeyProviderNotFoundError} when the default address has no registered provider.
929
+ */
930
+ getAuthorizerPublicKeys(): Promise<Uint8Array[]>;
846
931
  /**
847
932
  * Generates `TransactionAuthorization` (signatures) for a specific registered signer.
848
933
  * Mirrors `OotleWallet::authorize_transaction` from ootle-rs.
849
934
  *
935
+ * `authorizers` is the transaction's full authorizer set, this signer's keys among them.
936
+ *
850
937
  * @throws {KeyProviderNotFoundError} when no provider is registered for `signerAddress`.
851
938
  */
852
- authorizeTransaction(signerAddress: string, unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionAuthorization>;
939
+ authorizeTransaction(signerAddress: string, unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array, authorizers: Uint8Array[]): Promise<TransactionAuthorization>;
853
940
  /**
854
941
  * Collects authorizations from all registered key providers.
855
942
  * Useful when a transaction requires multiple signers.
943
+ *
944
+ * `authorizers` defaults to the keys of every registered provider; pass the full set when the
945
+ * transaction has authorizers outside this wallet.
856
946
  */
857
- authorizeTransactionAll(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionAuthorization[]>;
947
+ authorizeTransactionAll(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array, authorizers?: Uint8Array[]): Promise<TransactionAuthorization[]>;
858
948
  /**
859
949
  * Returns the key provider for a specific address, if registered.
860
950
  */
@@ -912,6 +1002,8 @@ export declare interface ParsedUtxo {
912
1002
  commitment: Uint8Array;
913
1003
  /** The on-chain output body (`public_nonce`, `encrypted_data`, ...). */
914
1004
  body: OutputBody;
1005
+ /** How the output is spent: a one-time spend key, a script, or both. */
1006
+ auth: SpendAuthorization;
915
1007
  }
916
1008
 
917
1009
  /**
@@ -1039,6 +1131,8 @@ declare interface ResolvedStealthInput {
1039
1131
  publicNonce: Uint8Array;
1040
1132
  /** The view secret that unblinded the input; the one-time spend key is derived from it too. */
1041
1133
  viewSecret: Uint8Array;
1134
+ /** The UTXO's one-time spend public key (from its on-chain spend authorization). */
1135
+ oneTimePublicKey: Uint8Array;
1042
1136
  }
1043
1137
 
1044
1138
  /**
@@ -1192,15 +1286,26 @@ export declare interface Signer {
1192
1286
  getAddress(): Promise<string>;
1193
1287
  /** Returns the raw public key bytes for this signer. */
1194
1288
  getPublicKey(): Promise<Uint8Array>;
1289
+ /**
1290
+ * The public keys this signer authorizes with, for the transaction's authorizer set.
1291
+ *
1292
+ * **Optional** — defaults to `[await getPublicKey()]`. Every authorizer signs over the full set,
1293
+ * so {@link signTransaction} (the free function) collects it from all signers before any of them
1294
+ * signs. Implement this only for a signer that contributes signatures from keys other than
1295
+ * {@link getPublicKey} (or more than one).
1296
+ */
1297
+ getAuthorizerPublicKeys?(): Promise<Uint8Array[]>;
1195
1298
  /**
1196
1299
  * Signs the given unsigned transaction and returns the collected signatures.
1197
1300
  *
1198
- * `sealPublicKey` is mixed into the transaction hash
1199
- * (`hashUnsignedTransaction(JSON.stringify(tx), sealPublicKey)`) so every signature in the
1200
- * final envelope verifies against the SAME hash — the engine's seal verification enforces
1201
- * this. Implementations MUST hash with the supplied `sealPublicKey`, not their own.
1301
+ * `sealPublicKey` and `authorizers` are mixed into the transaction hash
1302
+ * (`hashUnsignedTransaction(json, sealPublicKey, encodeAuthorizerSet(authorizers))`) so every
1303
+ * signature in the final envelope verifies against the SAME hash — the engine's seal verification
1304
+ * enforces this. `authorizers` is the public key of every authorizer of the transaction, this
1305
+ * signer's among them; the sealed transaction must carry an authorization from each key and no
1306
+ * other. Implementations MUST hash with the supplied values, not their own.
1202
1307
  */
1203
- signTransaction(transaction: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionSignature[]>;
1308
+ signTransaction(transaction: UnsignedTransactionV1, sealPublicKey: Uint8Array, authorizers: Uint8Array[]): Promise<TransactionSignature[]>;
1204
1309
  /**
1205
1310
  * Returns the view-only secret for stealth scanning/spending, if this signer holds one.
1206
1311
  *
@@ -1224,12 +1329,14 @@ export declare interface Signer {
1224
1329
  * @param publicNonce - The stealth output's sender public nonce (the DH counterparty).
1225
1330
  * @param sealPublicKey - The seal signer's public key, mixed into the transaction hash
1226
1331
  * (mirrors the `hashUnsignedTransaction` arg used by {@link Signer.signTransaction}).
1227
- * @param ctx - Injected crypto seam, so the signer never imports WASM directly, and the
1228
- * owner's 32-byte view secret, which the one-time spend key is derived from.
1332
+ * @param ctx - Injected crypto seam, so the signer never imports WASM directly; the
1333
+ * owner's 32-byte view secret, which the one-time spend key is derived from; and the
1334
+ * transaction's full authorizer set, which includes the one-time spend public key.
1229
1335
  */
1230
1336
  addStealthSignature?(unsignedJson: string, publicNonce: Uint8Array, sealPublicKey: Uint8Array, ctx: {
1231
1337
  crypto: SignerStealthCrypto;
1232
1338
  viewSecret: Uint8Array;
1339
+ authorizers: Uint8Array[];
1233
1340
  }): Promise<TransactionSignature>;
1234
1341
  }
1235
1342
 
@@ -1266,6 +1373,12 @@ export declare interface SignerStealthCrypto {
1266
1373
  *
1267
1374
  * The main signer is settled first with {@link resolveMainSigner}: a transaction that declares
1268
1375
  * none acts as the first signer.
1376
+ *
1377
+ * The authorizer set is collected from every signer ({@link collectAuthorizers}) before any of
1378
+ * them signs, since each signature commits to the whole set. The signatures are sealed in
1379
+ * ascending public-key order, as schema V2 requires.
1380
+ *
1381
+ * @throws {SignerError} when the signers' signatures are not exactly one per authorizer key.
1269
1382
  */
1270
1383
  export declare function signTransaction(signers: Signer[], unsignedTx: UnsignedTransactionV1, sealKeypair?: SealKeypair): Promise<SignedTransaction>;
1271
1384
 
@@ -1852,6 +1965,8 @@ export declare interface TransactionAuthorization {
1852
1965
  signatures: TransactionSignature[];
1853
1966
  }
1854
1967
 
1968
+ export { transactionBody }
1969
+
1855
1970
  /**
1856
1971
  * Fluent builder for constructing UnsignedTransactionV1 objects.
1857
1972
  *
@@ -1883,6 +1998,16 @@ export declare class TransactionBuilder {
1883
1998
  createAccount(ownerPublicKey: string, workspaceBucket?: string): this;
1884
1999
  createProof(account: ComponentAddress, resourceAddress: ResourceAddress): this;
1885
2000
  claimBurn(claim: MinotariBurnClaimProof): this;
2001
+ /**
2002
+ * Replace a component's method access rules (`SetComponentAccessRules`). The component's
2003
+ * `rules_updater`, fixed when it was created, decides who may: `Locked` components refuse it.
2004
+ */
2005
+ setComponentAccessRules(componentAddress: ComponentAddress, accessRules: ComponentAccessRules): this;
2006
+ /**
2007
+ * Replace a component's owner rule (`SetComponentOwnerRule`), as permitted by its
2008
+ * `rules_updater`.
2009
+ */
2010
+ setComponentOwnerRule(componentAddress: ComponentAddress, ownerRule: OwnerRule): this;
1886
2011
  allocateAddress(allocatableType: AllocatableAddressType, workspaceIdName: string): this;
1887
2012
  /**
1888
2013
  * Saves the last instruction output to a named workspace variable.
@@ -2066,6 +2191,8 @@ export declare class TransactionRejectedError extends OotleError {
2066
2191
  });
2067
2192
  }
2068
2193
 
2194
+ export { transactionSchemaVersion }
2195
+
2069
2196
  export { TransactionSignature }
2070
2197
 
2071
2198
  /** Raised when polling / SSE both timed out before the transaction finalized. */