@tari-project/ootle 0.11.1 → 0.12.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 +108 -17
  2. package/dist/index.js +383 -320
  3. package/package.json +4 -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
  *
@@ -968,8 +990,22 @@ declare interface ResolvedStealthInput {
968
990
  mask: Mask;
969
991
  /** The fetched UTXO's sender public nonce (`OutputBody.public_nonce`), raw bytes. */
970
992
  publicNonce: Uint8Array;
993
+ /** The view secret that unblinded the input; the one-time spend key is derived from it too. */
994
+ viewSecret: Uint8Array;
971
995
  }
972
996
 
997
+ /**
998
+ * Settles the transaction's main signer before anything signs it.
999
+ *
1000
+ * A transaction that declares none (`main_signer: "None"`, the `TransactionBuilder`
1001
+ * default) gets the first signer's key, `{ Authorizer: <public key hex> }` — the key the engine
1002
+ * used to act as before transactions declared it. Any other value is kept. Every signature
1003
+ * covers the main signer, so a signature made over the transaction before this ran does not
1004
+ * verify against the result: set it with `TransactionBuilder.withMainSigner` before handing the
1005
+ * transaction to a co-signer.
1006
+ */
1007
+ export declare function resolveMainSigner(signers: Signer[], unsignedTx: UnsignedTransactionV1): Promise<UnsignedTransactionV1>;
1008
+
973
1009
  /**
974
1010
  * Reads the chain tip and returns the `max_epoch` a transaction built now should carry:
975
1011
  * `currentEpoch + leadEpochs`.
@@ -1130,8 +1166,9 @@ export declare interface Signer {
1130
1166
  /**
1131
1167
  * Produces a one-time spend-key signature for a stealth input.
1132
1168
  *
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.
1169
+ * The signer derives the one-time spend scalar (`c + k`, keyed on the view secret
1170
+ * `ctx.viewSecret`) for the owned stealth UTXO via `ctx.crypto.stealthDhSecret(...)` and signs
1171
+ * the transaction hash with it.
1135
1172
  *
1136
1173
  * **Optional** — only signers that hold the owner secret (e.g. `SecretKeyWallet`) can
1137
1174
  * implement this. Daemon-delegated stealth is server-side and out of scope here.
@@ -1140,10 +1177,12 @@ export declare interface Signer {
1140
1177
  * @param publicNonce - The stealth output's sender public nonce (the DH counterparty).
1141
1178
  * @param sealPublicKey - The seal signer's public key, mixed into the transaction hash
1142
1179
  * (mirrors the `hashUnsignedTransaction` arg used by {@link Signer.signTransaction}).
1143
- * @param ctx - Injected crypto seam, so the signer never imports WASM directly.
1180
+ * @param ctx - Injected crypto seam, so the signer never imports WASM directly, and the
1181
+ * owner's 32-byte view secret, which the one-time spend key is derived from.
1144
1182
  */
1145
1183
  addStealthSignature?(unsignedJson: string, publicNonce: Uint8Array, sealPublicKey: Uint8Array, ctx: {
1146
1184
  crypto: SignerStealthCrypto;
1185
+ viewSecret: Uint8Array;
1147
1186
  }): Promise<TransactionSignature>;
1148
1187
  }
1149
1188
 
@@ -1159,7 +1198,7 @@ export declare class SignerError extends OotleError {
1159
1198
  * `WasmStealthCrypto` and `FakeStealthCrypto` flow through as-is.
1160
1199
  */
1161
1200
  export declare interface SignerStealthCrypto {
1162
- stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
1201
+ stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, viewSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
1163
1202
  }
1164
1203
 
1165
1204
  /**
@@ -1177,6 +1216,9 @@ export declare interface SignerStealthCrypto {
1177
1216
  * spend-key authorizations (which hash the tx with the seal public key) and into this
1178
1217
  * final seal — otherwise those signatures would be over a different hash and fail to
1179
1218
  * verify.
1219
+ *
1220
+ * The main signer is settled first with {@link resolveMainSigner}: a transaction that declares
1221
+ * none acts as the first signer.
1180
1222
  */
1181
1223
  export declare function signTransaction(signers: Signer[], unsignedTx: UnsignedTransactionV1, sealKeypair?: SealKeypair): Promise<SignedTransaction>;
1182
1224
 
@@ -1274,14 +1316,16 @@ export declare interface StealthCryptoProvider {
1274
1316
  */
1275
1317
  aggregateInputMasks(masks: Mask[]): Promise<Mask>;
1276
1318
  /**
1277
- * Derive the one-time stealth spend scalar (`c + k`) via DH for an owned stealth UTXO.
1319
+ * Derive the one-time stealth spend scalar (`c + k`, where `c = H(network || v·R)`) for an
1320
+ * owned stealth UTXO.
1278
1321
  *
1279
1322
  * @param networkByte - The network byte (see `Network`).
1280
- * @param ownerSecret - The owner's secret key.
1323
+ * @param ownerSecret - The owner's secret key `k`.
1324
+ * @param viewSecret - The owner's view secret key `v`.
1281
1325
  * @param publicNonce - The output's sender public nonce.
1282
1326
  * @returns The 32-byte spend scalar.
1283
1327
  */
1284
- stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
1328
+ stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, viewSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
1285
1329
  /**
1286
1330
  * Structurally validate a complete transfer envelope (balance proof filled). **Throws**
1287
1331
  * on invalid. This is a client pre-flight (`view_key = null`); the engine is
@@ -1813,6 +1857,39 @@ export declare class TransactionBuilder {
1813
1857
  */
1814
1858
  feeTransactionPayFromComponentConfidential(_componentAddress: ComponentAddress, _proof: ConfidentialWithdrawProof): this;
1815
1859
  dropAllProofsInWorkspace(): this;
1860
+ /**
1861
+ * Opens an authorization window over the workspace proof `proofName` for the instructions
1862
+ * that follow, until {@link dropProofAuthorization} closes it.
1863
+ *
1864
+ * A proof authorizes only inside a window its holder opens, and a window lends one hop: the
1865
+ * proof authorizes the calls made by the next instructions, not calls those make in turn.
1866
+ * Prefer {@link withAuthorizedProof}, which closes the window for you.
1867
+ *
1868
+ * @throws {InvalidArgumentError} if no workspace variable named `proofName` is defined.
1869
+ */
1870
+ authorizeProof(proofName: string): this;
1871
+ /**
1872
+ * Closes the authorization window {@link authorizeProof} opened over `proofName`.
1873
+ *
1874
+ * @throws {InvalidArgumentError} if no workspace variable named `proofName` is defined.
1875
+ */
1876
+ dropProofAuthorization(proofName: string): this;
1877
+ /**
1878
+ * Adds the instructions `build` adds inside an authorization window over the workspace
1879
+ * proof `proofName`, so the window covers exactly those instructions.
1880
+ *
1881
+ * @example
1882
+ * ```ts
1883
+ * builder
1884
+ * .createProof(account, badgeResource)
1885
+ * .saveVar("badge")
1886
+ * .withAuthorizedProof("badge", (b) => b.callMethod({ componentAddress, methodName: "admin_only" }, []))
1887
+ * .dropAllProofsInWorkspace();
1888
+ * ```
1889
+ *
1890
+ * @throws {InvalidArgumentError} if no workspace variable named `proofName` is defined.
1891
+ */
1892
+ withAuthorizedProof(proofName: string, build: (builder: this) => unknown): this;
1816
1893
  /**
1817
1894
  * Publishes a compiled WASM template. The binary is stored as a transaction
1818
1895
  * blob and referenced by index from the `PublishTemplate` instruction.
@@ -1847,6 +1924,16 @@ export declare class TransactionBuilder {
1847
1924
  addInput(input: SubstateRequirement | InputDeclaration): this;
1848
1925
  /** Declare several transaction inputs; see {@link addInput} for the `is_write` default. */
1849
1926
  withInputs(inputs: Array<SubstateRequirement | InputDeclaration>): this;
1927
+ /**
1928
+ * Sets the transaction's main signer: the key it acts as wherever the engine needs a single
1929
+ * signer (`OwnerRule::OwnedBySigner`, the caller's `transaction_signer_public_key`, a
1930
+ * published template's author). Every signature covers it, so it is fixed before signing.
1931
+ *
1932
+ * Defaults to `"None"`, which `signTransaction` replaces with the first signer's key
1933
+ * (`{ Authorizer: <public key hex> }`). Set it to name another authorizer, or to
1934
+ * `"SealSigner"` when the seal key itself should carry authority.
1935
+ */
1936
+ withMainSigner(mainSigner: MainSigner): this;
1850
1937
  /** @throws {InvalidArgumentError} if `minEpoch` is not a non-negative integer. */
1851
1938
  withMinEpoch(minEpoch: number): this;
1852
1939
  /**
@@ -1959,9 +2046,13 @@ export { UnsignedTransactionV1 }
1959
2046
  export declare type UnsignedTransactionWithBlobs = UnsignedTransactionV1;
1960
2047
 
1961
2048
  /**
1962
- * The value of a fetched substate, or `null` if the indexer answered that the
2049
+ * The decoded value of a fetched substate, or `null` if the indexer answered that the
1963
2050
  * requested version is down (only possible for a request with `include_proof`
1964
2051
  * that names the version).
2052
+ *
2053
+ * The indexer serves the value CBOR-encoded (`state.up.substate` is base64); this decodes it.
2054
+ *
2055
+ * @throws {CryptoBridgeError} if the served value is not a valid `SubstateValue` encoding.
1965
2056
  */
1966
2057
  export declare function upSubstateValue(response: IndexerGetSubstateResponse): SubstateValue | null;
1967
2058
 
@@ -2100,7 +2191,7 @@ export declare class WasmStealthCrypto implements StealthCryptoProvider {
2100
2191
  deriveAeadKey(privateKey: Uint8Array, publicKey: Uint8Array): Promise<Uint8Array>;
2101
2192
  unblindOutput(commitment: Uint8Array, encryptedData: Uint8Array, aeadKey: Uint8Array, skipMemo: boolean): Promise<DecryptedData>;
2102
2193
  aggregateInputMasks(masks: Mask[]): Promise<Mask>;
2103
- stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
2194
+ stealthDhSecret(networkByte: number, ownerSecret: Uint8Array, viewSecret: Uint8Array, publicNonce: Uint8Array): Promise<Uint8Array>;
2104
2195
  validateTransfer(statement: StealthTransferStatement): Promise<void>;
2105
2196
  }
2106
2197