@tari-project/ootle 0.11.1 → 0.13.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 +156 -17
  2. package/dist/index.js +424 -327
  3. package/package.json +5 -3
package/dist/index.d.ts CHANGED
@@ -5,6 +5,7 @@ import { ClaimedOutputTombstoneAddress } from '@tari-project/ootle-ts-bindings';
5
5
  import { ComponentAddress } from '@tari-project/ootle-ts-bindings';
6
6
  import { ConfidentialWithdrawProof } from '@tari-project/ootle-ts-bindings';
7
7
  import { Decision } from '@tari-project/ootle-ts-bindings';
8
+ import { Event as Event_2 } from '@tari-project/ootle-ts-bindings';
8
9
  import { ExecuteResult } from '@tari-project/ootle-ts-bindings';
9
10
  import { FinalizeOutcome } from '@tari-project/ootle-ts-bindings';
10
11
  import { FinalizeResult } from '@tari-project/ootle-ts-bindings';
@@ -22,11 +23,13 @@ import { Instruction } from '@tari-project/ootle-ts-bindings';
22
23
  import { InstructionArg } from '@tari-project/ootle-ts-bindings';
23
24
  import { ListRecentTransactionsRequest } from '@tari-project/ootle-ts-bindings';
24
25
  import { ListRecentTransactionsResponse } from '@tari-project/ootle-ts-bindings';
26
+ import { MainSigner } from '@tari-project/ootle-ts-bindings';
25
27
  import { MinotariBurnClaimProof } from '@tari-project/ootle-ts-bindings';
26
28
  import { NonFungibleAddress } from '@tari-project/ootle-ts-bindings';
27
29
  import { OutputBody } from '@tari-project/ootle-ts-bindings';
28
30
  import { PublishedTemplateAddress } from '@tari-project/ootle-ts-bindings';
29
31
  import { RejectReason } from '@tari-project/ootle-ts-bindings';
32
+ import { Resource } from '@tari-project/ootle-ts-bindings';
30
33
  import { ResourceAddress } from '@tari-project/ootle-ts-bindings';
31
34
  import { RistrettoPublicKeyBytes } from '@tari-project/ootle-ts-bindings';
32
35
  import { StealthTransferStatement as StealthTransferStatement_2 } from '@tari-project/ootle-ts-bindings';
@@ -35,10 +38,12 @@ import { SubstateRequirement } from '@tari-project/ootle-ts-bindings';
35
38
  import { SubstateValue } from '@tari-project/ootle-ts-bindings';
36
39
  import { Transaction } from '@tari-project/ootle-ts-bindings';
37
40
  import { TransactionEnvelope } from '@tari-project/ootle-ts-bindings';
41
+ import { TransactionReceipt } from '@tari-project/ootle-ts-bindings';
38
42
  import { TransactionSignature } from '@tari-project/ootle-ts-bindings';
39
43
  import { TransactionV1 } from '@tari-project/ootle-ts-bindings';
40
44
  import { UnsealedTransactionV1 } from '@tari-project/ootle-ts-bindings';
41
45
  import { UnsignedTransactionV1 } from '@tari-project/ootle-ts-bindings';
46
+ import { Utxo } from '@tari-project/ootle-ts-bindings';
42
47
  import { UtxoAddress } from '@tari-project/ootle-ts-bindings';
43
48
  import { ValidatorFeePoolAddress } from '@tari-project/ootle-ts-bindings';
44
49
  import { VaultId } from '@tari-project/ootle-ts-bindings';
@@ -157,7 +162,7 @@ export declare class AuthorizedTransfer {
157
162
  * revealed-only transfer).
158
163
  *
159
164
  * For each resolved input, picks the owner's signer from the wallet and calls its
160
- * `addStealthSignature(unsignedJson, publicNonce, sealPublicKey, { crypto })` — which
165
+ * `addStealthSignature(unsignedJson, publicNonce, sealPublicKey, { crypto, viewSecret })` — which
161
166
  * derives the one-time spend scalar via `stealthDhSecret` and signs the tx hash. The
162
167
  * secret stays in the signer (never pulled into the transfer).
163
168
  *
@@ -256,14 +261,11 @@ declare interface BalanceProofSignatureJson {
256
261
  export declare function boolLiteral(value: boolean): InstructionArg;
257
262
 
258
263
  /**
259
- * Assemble a TransactionSignature from a 32-byte public key and a Schnorr
260
- * `(public_nonce, signature)` pair. Asserts the 32-byte length on all three
261
- * inputs at the trust boundary so length regressions surface here, not deeper.
264
+ * Assemble a TransactionSignature from a 32-byte public key and a 64-byte sr25519 signature
265
+ * (the public nonce `R`, then the scalar `s` with the sr25519 marker bit set in its last byte).
266
+ * Asserts both lengths at the trust boundary so length regressions surface here, not deeper.
262
267
  */
263
- export declare function buildTransactionSignature(publicKey: Uint8Array, sig: {
264
- public_nonce: Uint8Array;
265
- signature: Uint8Array;
266
- }): TransactionSignature;
268
+ export declare function buildTransactionSignature(publicKey: Uint8Array, signature: Uint8Array): TransactionSignature;
267
269
 
268
270
  /**
269
271
  * Internal base for 32-byte stealth-domain carriers (`Mask`, `StealthInput`).
@@ -294,6 +296,8 @@ export declare function claimedOutputTombstoneAddressLiteral(address: ClaimedOut
294
296
  /**
295
297
  * @throws {InvalidArgumentError} if `result` carries an unrecognised `final_decision`
296
298
  * variant (an indexer protocol mismatch — defence-in-depth).
299
+ * @throws {CryptoBridgeError} if an aborted result carries an `execution_result` that does not
300
+ * decode.
297
301
  */
298
302
  export declare function classifyOutcome(result: IndexerTransactionFinalizedResult): {
299
303
  outcome: FinalizeOutcome | "Reject";
@@ -354,6 +358,24 @@ export declare class CryptoBridgeError extends OotleError {
354
358
 
355
359
  export { Decision }
356
360
 
361
+ /** Decodes a base64 CBOR `Event`, as served by the transaction event query and stream. */
362
+ export declare function decodeEvent(encoded: string): Event_2;
363
+
364
+ /** Decodes a base64 CBOR `ExecuteResult`, as in a finalized transaction's `execution_result`. */
365
+ export declare function decodeExecuteResult(encoded: string): ExecuteResult;
366
+
367
+ /** Decodes a base64 CBOR `Resource`, as served by `/resources/{address}`. */
368
+ export declare function decodeResource(encoded: string): Resource;
369
+
370
+ /** Decodes a base64 CBOR `SubstateValue`, as in `SubstateState.up.substate` and `EncodedSubstate.value`. */
371
+ export declare function decodeSubstateValue(encoded: string): SubstateValue;
372
+
373
+ /** Decodes a base64 CBOR `TransactionReceipt`, as served by `/transaction-receipts`. */
374
+ export declare function decodeTransactionReceipt(encoded: string): TransactionReceipt;
375
+
376
+ /** Decodes a base64 CBOR `Utxo`, as served by `/utxos`. */
377
+ export declare function decodeUtxo(encoded: string): Utxo;
378
+
357
379
  /**
358
380
  * The result of decrypting an owned output via the AEAD path (`unblindOutput`).
359
381
  *
@@ -451,6 +473,54 @@ export declare class EncryptedData {
451
473
 
452
474
  export { ExecuteResult }
453
475
 
476
+ /**
477
+ * A {@link Signer} whose key is held externally. Each `signTransaction` hashes the transaction
478
+ * against the supplied seal public key, asks `sign` for a signature over the hash, and verifies it
479
+ * before returning, so a wrong key or scheme fails here with a {@link SignerError}. An error thrown
480
+ * by `sign` itself (a vault rejection or timeout) is also rethrown as a {@link SignerError}, with the
481
+ * original as its `cause`.
482
+ *
483
+ * @example
484
+ * ```ts
485
+ * const signer = new ExternalKeySigner({
486
+ * publicKey,
487
+ * viewPublicKey,
488
+ * network: Network.Esmeralda,
489
+ * sign: (hash) => vault.sign(keyId, hash),
490
+ * });
491
+ * const signed = await signTransaction([signer], unsignedTx);
492
+ * ```
493
+ */
494
+ export declare class ExternalKeySigner implements Signer {
495
+ private readonly publicKey;
496
+ private readonly sign;
497
+ readonly address: string;
498
+ constructor(options: ExternalKeySignerOptions);
499
+ getAddress(): Promise<string>;
500
+ getPublicKey(): Promise<Uint8Array>;
501
+ signTransaction(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionSignature[]>;
502
+ }
503
+
504
+ export declare interface ExternalKeySignerOptions {
505
+ /** The 32-byte public key of the external key. */
506
+ publicKey: Uint8Array;
507
+ /** The 32-byte view-only public key; with `publicKey` it forms the Ootle address. */
508
+ viewPublicKey: Uint8Array;
509
+ network: Network;
510
+ /** Signs the authorization hash (`hashUnsignedTransaction`). */
511
+ sign: ExternalSignFn;
512
+ }
513
+
514
+ /**
515
+ * Signs a 64-byte transaction hash with a key held outside this process (an HSM, an MPC vault, a
516
+ * hardware wallet) and returns the raw 64-byte signature.
517
+ *
518
+ * The signature must be a standard sr25519 (schnorrkel) signature over `message` exactly as given,
519
+ * under the default `substrate` signing context, with the sr25519 marker bit set in its last byte.
520
+ * A signer that hashes, prefixes or wraps the message produces a signature that fails verification.
521
+ */
522
+ export declare type ExternalSignFn = (message: Uint8Array) => Promise<Uint8Array>;
523
+
454
524
  /**
455
525
  * Fluent builder for common faucet component invocations.
456
526
  * Mirrors `FaucetInvokeBuilder` from the Rust ootle-rs crate.
@@ -968,8 +1038,22 @@ declare interface ResolvedStealthInput {
968
1038
  mask: Mask;
969
1039
  /** The fetched UTXO's sender public nonce (`OutputBody.public_nonce`), raw bytes. */
970
1040
  publicNonce: Uint8Array;
1041
+ /** The view secret that unblinded the input; the one-time spend key is derived from it too. */
1042
+ viewSecret: Uint8Array;
971
1043
  }
972
1044
 
1045
+ /**
1046
+ * Settles the transaction's main signer before anything signs it.
1047
+ *
1048
+ * A transaction that declares none (`main_signer: "None"`, the `TransactionBuilder`
1049
+ * default) gets the first signer's key, `{ Authorizer: <public key hex> }` — the key the engine
1050
+ * used to act as before transactions declared it. Any other value is kept. Every signature
1051
+ * covers the main signer, so a signature made over the transaction before this ran does not
1052
+ * verify against the result: set it with `TransactionBuilder.withMainSigner` before handing the
1053
+ * transaction to a co-signer.
1054
+ */
1055
+ export declare function resolveMainSigner(signers: Signer[], unsignedTx: UnsignedTransactionV1): Promise<UnsignedTransactionV1>;
1056
+
973
1057
  /**
974
1058
  * Reads the chain tip and returns the `max_epoch` a transaction built now should carry:
975
1059
  * `currentEpoch + leadEpochs`.
@@ -1130,8 +1214,9 @@ export declare interface Signer {
1130
1214
  /**
1131
1215
  * Produces a one-time spend-key signature for a stealth input.
1132
1216
  *
1133
- * The signer derives the one-time spend scalar (`c + k`) for the owned stealth UTXO via
1134
- * `ctx.crypto.stealthDhSecret(...)` and signs the transaction hash with it.
1217
+ * The signer derives the one-time spend scalar (`c + k`, keyed on the view secret
1218
+ * `ctx.viewSecret`) for the owned stealth UTXO via `ctx.crypto.stealthDhSecret(...)` and signs
1219
+ * the transaction hash with it.
1135
1220
  *
1136
1221
  * **Optional** — only signers that hold the owner secret (e.g. `SecretKeyWallet`) can
1137
1222
  * implement this. Daemon-delegated stealth is server-side and out of scope here.
@@ -1140,10 +1225,12 @@ export declare interface Signer {
1140
1225
  * @param publicNonce - The stealth output's sender public nonce (the DH counterparty).
1141
1226
  * @param sealPublicKey - The seal signer's public key, mixed into the transaction hash
1142
1227
  * (mirrors the `hashUnsignedTransaction` arg used by {@link Signer.signTransaction}).
1143
- * @param ctx - Injected crypto seam, so the signer never imports WASM directly.
1228
+ * @param ctx - Injected crypto seam, so the signer never imports WASM directly, and the
1229
+ * owner's 32-byte view secret, which the one-time spend key is derived from.
1144
1230
  */
1145
1231
  addStealthSignature?(unsignedJson: string, publicNonce: Uint8Array, sealPublicKey: Uint8Array, ctx: {
1146
1232
  crypto: SignerStealthCrypto;
1233
+ viewSecret: Uint8Array;
1147
1234
  }): Promise<TransactionSignature>;
1148
1235
  }
1149
1236
 
@@ -1159,7 +1246,7 @@ export declare class SignerError extends OotleError {
1159
1246
  * `WasmStealthCrypto` and `FakeStealthCrypto` flow through as-is.
1160
1247
  */
1161
1248
  export declare interface SignerStealthCrypto {
1162
- stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
1249
+ stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, viewSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
1163
1250
  }
1164
1251
 
1165
1252
  /**
@@ -1177,6 +1264,9 @@ export declare interface SignerStealthCrypto {
1177
1264
  * spend-key authorizations (which hash the tx with the seal public key) and into this
1178
1265
  * final seal — otherwise those signatures would be over a different hash and fail to
1179
1266
  * verify.
1267
+ *
1268
+ * The main signer is settled first with {@link resolveMainSigner}: a transaction that declares
1269
+ * none acts as the first signer.
1180
1270
  */
1181
1271
  export declare function signTransaction(signers: Signer[], unsignedTx: UnsignedTransactionV1, sealKeypair?: SealKeypair): Promise<SignedTransaction>;
1182
1272
 
@@ -1274,14 +1364,16 @@ export declare interface StealthCryptoProvider {
1274
1364
  */
1275
1365
  aggregateInputMasks(masks: Mask[]): Promise<Mask>;
1276
1366
  /**
1277
- * Derive the one-time stealth spend scalar (`c + k`) via DH for an owned stealth UTXO.
1367
+ * Derive the one-time stealth spend scalar (`c + k`, where `c = H(network || v·R)`) for an
1368
+ * owned stealth UTXO.
1278
1369
  *
1279
1370
  * @param networkByte - The network byte (see `Network`).
1280
- * @param ownerSecret - The owner's secret key.
1371
+ * @param ownerSecret - The owner's secret key `k`.
1372
+ * @param viewSecret - The owner's view secret key `v`.
1281
1373
  * @param publicNonce - The output's sender public nonce.
1282
1374
  * @returns The 32-byte spend scalar.
1283
1375
  */
1284
- stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
1376
+ stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, viewSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
1285
1377
  /**
1286
1378
  * Structurally validate a complete transfer envelope (balance proof filled). **Throws**
1287
1379
  * on invalid. This is a client pre-flight (`view_key = null`); the engine is
@@ -1813,6 +1905,39 @@ export declare class TransactionBuilder {
1813
1905
  */
1814
1906
  feeTransactionPayFromComponentConfidential(_componentAddress: ComponentAddress, _proof: ConfidentialWithdrawProof): this;
1815
1907
  dropAllProofsInWorkspace(): this;
1908
+ /**
1909
+ * Opens an authorization window over the workspace proof `proofName` for the instructions
1910
+ * that follow, until {@link dropProofAuthorization} closes it.
1911
+ *
1912
+ * A proof authorizes only inside a window its holder opens, and a window lends one hop: the
1913
+ * proof authorizes the calls made by the next instructions, not calls those make in turn.
1914
+ * Prefer {@link withAuthorizedProof}, which closes the window for you.
1915
+ *
1916
+ * @throws {InvalidArgumentError} if no workspace variable named `proofName` is defined.
1917
+ */
1918
+ authorizeProof(proofName: string): this;
1919
+ /**
1920
+ * Closes the authorization window {@link authorizeProof} opened over `proofName`.
1921
+ *
1922
+ * @throws {InvalidArgumentError} if no workspace variable named `proofName` is defined.
1923
+ */
1924
+ dropProofAuthorization(proofName: string): this;
1925
+ /**
1926
+ * Adds the instructions `build` adds inside an authorization window over the workspace
1927
+ * proof `proofName`, so the window covers exactly those instructions.
1928
+ *
1929
+ * @example
1930
+ * ```ts
1931
+ * builder
1932
+ * .createProof(account, badgeResource)
1933
+ * .saveVar("badge")
1934
+ * .withAuthorizedProof("badge", (b) => b.callMethod({ componentAddress, methodName: "admin_only" }, []))
1935
+ * .dropAllProofsInWorkspace();
1936
+ * ```
1937
+ *
1938
+ * @throws {InvalidArgumentError} if no workspace variable named `proofName` is defined.
1939
+ */
1940
+ withAuthorizedProof(proofName: string, build: (builder: this) => unknown): this;
1816
1941
  /**
1817
1942
  * Publishes a compiled WASM template. The binary is stored as a transaction
1818
1943
  * blob and referenced by index from the `PublishTemplate` instruction.
@@ -1847,6 +1972,16 @@ export declare class TransactionBuilder {
1847
1972
  addInput(input: SubstateRequirement | InputDeclaration): this;
1848
1973
  /** Declare several transaction inputs; see {@link addInput} for the `is_write` default. */
1849
1974
  withInputs(inputs: Array<SubstateRequirement | InputDeclaration>): this;
1975
+ /**
1976
+ * Sets the transaction's main signer: the key it acts as wherever the engine needs a single
1977
+ * signer (`OwnerRule::OwnedBySigner`, the caller's `transaction_signer_public_key`, a
1978
+ * published template's author). Every signature covers it, so it is fixed before signing.
1979
+ *
1980
+ * Defaults to `"None"`, which `signTransaction` replaces with the first signer's key
1981
+ * (`{ Authorizer: <public key hex> }`). Set it to name another authorizer, or to
1982
+ * `"SealSigner"` when the seal key itself should carry authority.
1983
+ */
1984
+ withMainSigner(mainSigner: MainSigner): this;
1850
1985
  /** @throws {InvalidArgumentError} if `minEpoch` is not a non-negative integer. */
1851
1986
  withMinEpoch(minEpoch: number): this;
1852
1987
  /**
@@ -1959,9 +2094,13 @@ export { UnsignedTransactionV1 }
1959
2094
  export declare type UnsignedTransactionWithBlobs = UnsignedTransactionV1;
1960
2095
 
1961
2096
  /**
1962
- * The value of a fetched substate, or `null` if the indexer answered that the
2097
+ * The decoded value of a fetched substate, or `null` if the indexer answered that the
1963
2098
  * requested version is down (only possible for a request with `include_proof`
1964
2099
  * that names the version).
2100
+ *
2101
+ * The indexer serves the value CBOR-encoded (`state.up.substate` is base64); this decodes it.
2102
+ *
2103
+ * @throws {CryptoBridgeError} if the served value is not a valid `SubstateValue` encoding.
1965
2104
  */
1966
2105
  export declare function upSubstateValue(response: IndexerGetSubstateResponse): SubstateValue | null;
1967
2106
 
@@ -2100,7 +2239,7 @@ export declare class WasmStealthCrypto implements StealthCryptoProvider {
2100
2239
  deriveAeadKey(privateKey: Uint8Array, publicKey: Uint8Array): Promise<Uint8Array>;
2101
2240
  unblindOutput(commitment: Uint8Array, encryptedData: Uint8Array, aeadKey: Uint8Array, skipMemo: boolean): Promise<DecryptedData>;
2102
2241
  aggregateInputMasks(masks: Mask[]): Promise<Mask>;
2103
- stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
2242
+ stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, viewSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
2104
2243
  validateTransfer(statement: StealthTransferStatement): Promise<void>;
2105
2244
  }
2106
2245