@arcanetech/privacy-sdk-stellar 0.5.1 → 0.5.4

package/README.md

@@ -16,6 +16,7 @@ This package provides:
 - `buildBlindedRecipientTagChallengeMessage()` (`@arcanetech/privacy-sdk-stellar/transact`) — builds the wallet-signed challenge used to issue blinded recipient tags so a recipient can discover escrow notes after they register
 - `fetchEscrowOutputNoteEvents({ transactEnvironment, txId, poolAddress })` — loads escrow output-note ciphertexts for a claim using the environment's network configuration
 - `unsignedEscrowAuthorizationForSweep({ prepared, transactEnvironment, relayerPublicKey })` — simulates the relayer invocation and returns the unsigned claimant authorization entry to sign offline
+- Protocol fee: deposit, transfer, and withdraw quote Required Fee and attach a private Fee Output (2×2 for deposit/withdraw, 6×6 for transfer with change). Escrow sweep does not attach a Fee Output.
 
 ## Browser Example
 

package/dist/index.d.ts

@@ -231,14 +231,15 @@ interface StellarTransactEnvironment {
     network: StellarNetworkConfig;
     /**
      * Nonce (persistent storage key) of the pool's `ZkConfig` entry this
-     * environment's proofs/circuit shape target. Defaults to `2n` (Commitment
-     * V2, 95 public signals) when omitted. Nonce `0` is the retired 93-signal
-     * layout and must be passed explicitly.
+     * environment's proofs/circuit shape target. Defaults to `3n` (bundled 2×2
+     * binding layout) when omitted. Also bundled: `7n` (6×6). The value must
+     * match the on-chain pool config or bootstrap/execute fails with
+     * `no zk circuit configured for nonce …`.
      */
     zkConfigNonce?: bigint;
     /**
-     * Optional nonce-keyed circuit map. Defaults to the SDK bundled 2×2 (nonce 2)
-     * and 6×6 (nonce 6) schemes. URL fields are only for a custom/dev circuit.
+     * Optional nonce-keyed circuit map. Defaults to the SDK bundled 2×2 (nonce 3)
+     * and 6×6 (nonce 7) schemes. URL fields are only for a custom/dev circuit.
      */
     zkCircuits?: Record<string, StellarZkCircuitDefinition>;
     /**
@@ -307,6 +308,7 @@ interface StellarTransactArtifacts {
     };
     executeFinalizeRequired?: boolean;
     spendSource?: 'privateAddress' | 'escrow';
+    zkConfigNonce?: bigint;
 }
 interface StellarOperationReceipt {
     operationId: string;
@@ -363,6 +365,12 @@ interface FetchContractMerkleResult {
     merkleRootHex: string;
     updatedAt: number;
 }
+/**
+ * Loads pool Merkle leaves without `get_commitments()`. That helper walks the
+ * whole tree in one simulate and exceeds the Soroban host budget on a live
+ * stand. Completes the cached prefix from persistent `TreeDataKey::Leaf`
+ * ledger entries instead.
+ */
 declare function fetchAndMergeMerkleState(parameters: {
     poolContractId: string;
     walletPublicKey: string;
@@ -765,6 +773,17 @@ declare function encodePrivateAddressFromHexCoordinates(publicKeyXHex: string, p
 declare function recipientPublicKeysDecimalFromPrivateAddress(value: string): unknown;
 declare function privateAddressSdk(sdk: PrivacyPoolSDK): PrivateAddressSdk;
 
+type FeeOutputSpec = {
+    requiredFee: bigint;
+    feeCollectorPrivateAddress: string;
+};
+
+type FeeOutputKindInput = {
+    kind: OperationKind;
+    spendSource?: StellarTransactArtifacts['spendSource'];
+    escrowSend?: boolean;
+};
+
 declare class PrivacyPoolService {
     private readonly assets?;
     private readonly applicationId?;
@@ -772,11 +791,12 @@ declare class PrivacyPoolService {
     private readonly zkCircuits?;
     private readonly zkConfigNonce?;
     private readonly zkArtifactBaseUrl?;
-    private sdk;
-    private initPromise;
+    private readonly sdks;
+    private readonly initPromises;
     constructor(assets?: StellarBrowserAssets | undefined, applicationId?: string | undefined, auditPublicKey?: [string, string] | undefined, zkCircuits?: Record<string, StellarZkCircuitDefinition> | undefined, zkConfigNonce?: bigint | undefined, zkArtifactBaseUrl?: string | undefined);
-    private ensureInit;
-    getInitializedSdk(): Promise<PrivacyPoolSDK>;
+    getInitializedSdk(nonce?: bigint): Promise<PrivacyPoolSDK>;
+    feeBearingZkConfigNonce(input: FeeOutputKindInput): bigint;
+    private initializeSdk;
     getAuditPublicKey(): [string, string] | undefined;
     getApplicationId(): string;
     generatePrivateAddressFromStellarSignature(signature: string, domain: SpendScalarDomain): Promise<string>;
@@ -800,6 +820,8 @@ declare class PrivacyPoolService {
         depositScalarHex: string;
         merkleRootBytes: Buffer$1;
         tokenAddress: string;
+        publicDepositStroops?: bigint;
+        feeOutput?: FeeOutputSpec;
     }): Promise<ProofResult>;
     calculateNullifierHash(nullifier: string, privKeyScalar: string): Promise<string>;
     prepareWithdrawTransactProof(parameters: {
@@ -811,6 +833,7 @@ declare class PrivacyPoolService {
         withdrawAmountStroops: bigint;
         changePrivateAddressStpl1: string | undefined;
         tokenAddress: string;
+        feeOutput?: FeeOutputSpec;
     }): Promise<ProofWithChange>;
     prepareWithdrawTransactProofDual(parameters: {
         coinA: CoinData;
@@ -823,6 +846,7 @@ declare class PrivacyPoolService {
         withdrawAmountStroops: bigint;
         changePrivateAddressStpl1: string | undefined;
         tokenAddress: string;
+        feeOutput?: FeeOutputSpec;
     }): Promise<ProofWithChange>;
 }
 
@@ -955,7 +979,9 @@ declare function loadDefaultStellarBrowserAssets(options?: {
 
 declare const STANDARD_ZK_CONFIG_NONCE = 0n;
 declare const COMMITMENT_V2_ZK_NONCE = 2n;
+declare const BINDING_ZK_NONCE = 3n;
 declare const SIX_BY_SIX_ZK_NONCE = 6n;
+declare const SIX_BY_SIX_BINDING_ZK_NONCE = 7n;
 declare const DEFAULT_ZK_CONFIG_NONCE = 3n;
 declare function resolveZkConfigNonce(transactEnvironment: StellarTransactEnvironment): bigint;
 
@@ -1003,6 +1029,7 @@ interface SubmitSorobanConfidentialTransferInput {
     ciphertextHex?: string;
     outputNoteEphemeralScalars?: string[];
     applicationIdsPlaintext?: KytApplicationIdHints;
+    zkConfigNonce?: bigint;
     networkPassphrase: string;
     sorobanRpcUrl: string;
     transactEnvironment: StellarTransactEnvironment;
@@ -1032,6 +1059,7 @@ type PrepareConfidentialTransferProofDualParameters = {
     tokenAddress: string;
     escrowSend?: TransferEscrowSend;
     escrowClaimantLimbs?: TransferEscrowClaimantLimbs;
+    feeOutput?: FeeOutputSpec;
 };
 type PrepareConfidentialTransferProofDualResult = {
     proof_hex: string;
@@ -1055,6 +1083,7 @@ type PrepareConfidentialTransferProofParameters = {
     tokenAddress: string;
     escrowSend?: TransferEscrowSend;
     escrowClaimantLimbs?: TransferEscrowClaimantLimbs;
+    feeOutput?: FeeOutputSpec;
 };
 type PrepareConfidentialTransferProofResult = {
     proof_hex: string;
@@ -1084,6 +1113,7 @@ interface RequestKytPassageForPoolInteractionInput {
     outputNoteEphemeralScalars?: string[];
     decryptedAuditSlots?: DecryptedKytAuditSlot[];
     applicationIdsPlaintext?: KytApplicationIdHints;
+    zkConfigNonce?: bigint;
     networkPassphrase: string;
     sorobanRpcUrl: string;
     transactEnvironment: StellarTransactEnvironment;
@@ -1201,4 +1231,4 @@ declare function isEscrowPreparedOperation(prepared: StellarPreparedOperation):
 declare function evaluateRequiredSubmissionMethod(prepared: StellarPreparedOperation, zkConfigNonce?: bigint): RequiredSubmissionMethodResult;
 declare function requiredSubmissionMethod(prepared: StellarPreparedOperation, zkConfigNonce?: bigint): SubmissionMethod;
 
-export { type AlignedDepositSlot, type BlindedRecipientTagChallengeFields, COMMITMENT_V2_ZK_NONCE, type CreateStellarPrivacyClientResult, DEFAULT_STELLAR_ZK_CIRCUITS, DEFAULT_ZK_CONFIG_NONCE, ESCROW_SUBMISSION_REFUSAL, type EscrowOutputNoteCiphertextEvent, type EscrowSubmissionRefusal, EscrowSubmissionRefusedError, type KytApplicationIdHints, KytInspectError, type LoadBrowserAssetsInput, MIN_CONFIDENTIAL_TRANSFER_STROOPS, type PrepareRelayTransactPackageFromPreparedInput, type PrepareRelayTransactPackageInput, PrivacyPoolService, type ProofResult, type ProofWithChange, RELAY_SIGNAL_INDEX_ESCROW_RECIPIENT_HI, RELAY_SIGNAL_INDEX_ESCROW_RECIPIENT_LO, RELAY_SIGNAL_INDEX_NULLIFIER_0, RELAY_SIGNAL_INDEX_NULLIFIER_1, RELAY_SIGNAL_INDEX_PUBLIC_DEPOSIT, RELAY_SIGNAL_INDEX_PUBLIC_DEPOSIT_ASSET_HI, RELAY_SIGNAL_INDEX_PUBLIC_DEPOSIT_ASSET_LO, RELAY_SIGNAL_INDEX_PUBLIC_WITHDRAWAL, RELAY_SIGNAL_INDEX_PUBLIC_WITHDRAWAL_ASSET_HI, RELAY_SIGNAL_INDEX_PUBLIC_WITHDRAWAL_ASSET_LO, RELAY_SIGNAL_INDEX_STATE_ROOT, RELAY_SIGNAL_INDEX_WITHDRAW_ADDRESS_HI, RELAY_SIGNAL_INDEX_WITHDRAW_ADDRESS_LO, RELAY_TRANSACT_FIELD_BYTES, RELAY_TRANSACT_PACKAGE_VERSION_V1, RELAY_TRANSACT_SIGNAL_PREFIX_BYTES, RELAY_TRANSACT_SUPPORTED_SIGNAL_COUNT, type ReconstructedEscrowNote, type RelayKeyVersionHints, type RelayTransactPackageV1, type RelayTransactPackageVersion, type RelayTransactPublicLegContext, type RelayTransactSupportedProfile, type RequestKytPassageForPoolInteractionInput, type RequiredSubmissionMethodResult, SIX_BY_SIX_ZK_NONCE, STANDARD_ZK_CONFIG_NONCE, SUBMISSION_METHOD, type StellarAddress, type StellarAsset, type StellarAssetId, type StellarAssetsCatalog, type StellarAvailablePrivateRecordsFilter, type StellarBrowserAssets, type StellarBrowserPrivacyClientConfig, type StellarBundledZkCircuitDefinition, type StellarCustomZkCircuitDefinition, type StellarDeliverySyncState, type StellarIncomingDeliveriesFilter, type StellarIncomingDelivery, type StellarKytEnvironment, type StellarLeafEphemeral, type StellarNetworkConfig, type StellarOperationReceipt, type StellarPolicyAdapter, type StellarPoolMerkleState, type StellarPreparedOperation, type StellarPrivacyClient, type StellarPrivacyClientConfig, type StellarPrivateAssetRow, type StellarPrivateRecord, type StellarPrivateRecordStatus, type StellarPublicBalance, type StellarPublicBalanceInput, type StellarRegistryLookup, type StellarStateAdapter, type StellarSubmissionPayload, type StellarTransactEngine, type StellarTransactEnvironment, type StellarTransactionDetails, type StellarTransactionStatus, type StellarTransferFromAddress, type StellarTransferIntent, type StellarZkCircuitDefinition, type SubmissionMethod, type TransferEscrowClaimantLimbs, type TransferEscrowSend, type TransferRecipientExecutionContext, type TransferTemporaryRecipientKey, ZERO_STROOPS, assertEscrowSweepClaimant, assetLegToTokenAddress, attachEscrowAuthorization, attachPoolStatePorts, buildBlindedRecipientTagChallengeMessage, buildPoolTransactionAuditParameters, buildPrivateAddressSignMessage, configurePrivacyPoolService, createDefaultTransactEngine, createPrivacyPoolService, createStellarPolicyAdapterFromEnvironment, createStellarPrivacyClient, createStellarPrivacyClientFromResolvedConfig, decodePrivateAddress, deriveEscrowRecipientFromStellarAddress, encodePrivateAddress, encodePrivateAddressFromHexCoordinates, evaluateRequiredSubmissionMethod, fetchAndMergeMerkleState, fetchEscrowOutputNoteEvents, finalizeSpendOperationAtExecute, frDecimalToPaddedBytes32, generateRandomDepositScalarHex, generateTemporaryRecipientPrivateAddress, getPrivacyPoolService, isEscrowPreparedOperation, isStellarPrivacyClient, listWalletPrivateAddressRecordsForOwnerFromStateSnapshot, listWalletPrivateAddressScalarsForOwnerFromStateSnapshot, loadDefaultStellarBrowserAssets, loadStellarBrowserAssets, optionalZkArtifactBaseUrl, parseAuditPublicKeyFromEnvHex, parseKytReasonCode, prepareConfidentialTransferProof, prepareConfidentialTransferProofDual, prepareEscrowSweepOperation, prepareRelayTransactPackage, prepareRelayTransactPackageFromPrepared, privateAddressSdk, readLeafEphemeralHex, readPrivateRecordsFromStateSnapshot, readRelayTransactSupportedProfile, readWalletDefaultPrivateAddressNonceFromStateSnapshot, readWalletPrivateAddressRecordFromStateSnapshot, readWalletPrivateAddressScalarFromStateSnapshot, recipientPublicKeysDecimalFromPrivateAddress, reconstructEscrowNote, requestKytPassageForPoolInteraction, requiredSubmissionMethod, resolvePoolApplicationId, resolveStellarPrivacyClientConfig, resolveZkConfigNonce, runTtlPreflight, stellarStateDefinitions, submitSorobanConfidentialTransfer, submitSorobanDeposit, tokenAddressToAssetLeg, unsignedEscrowAuthorizationForSweep };
+export { type AlignedDepositSlot, BINDING_ZK_NONCE, type BlindedRecipientTagChallengeFields, COMMITMENT_V2_ZK_NONCE, type CreateStellarPrivacyClientResult, DEFAULT_STELLAR_ZK_CIRCUITS, DEFAULT_ZK_CONFIG_NONCE, ESCROW_SUBMISSION_REFUSAL, type EscrowOutputNoteCiphertextEvent, type EscrowSubmissionRefusal, EscrowSubmissionRefusedError, type KytApplicationIdHints, KytInspectError, type LoadBrowserAssetsInput, MIN_CONFIDENTIAL_TRANSFER_STROOPS, type PrepareRelayTransactPackageFromPreparedInput, type PrepareRelayTransactPackageInput, PrivacyPoolService, type ProofResult, type ProofWithChange, RELAY_SIGNAL_INDEX_ESCROW_RECIPIENT_HI, RELAY_SIGNAL_INDEX_ESCROW_RECIPIENT_LO, RELAY_SIGNAL_INDEX_NULLIFIER_0, RELAY_SIGNAL_INDEX_NULLIFIER_1, RELAY_SIGNAL_INDEX_PUBLIC_DEPOSIT, RELAY_SIGNAL_INDEX_PUBLIC_DEPOSIT_ASSET_HI, RELAY_SIGNAL_INDEX_PUBLIC_DEPOSIT_ASSET_LO, RELAY_SIGNAL_INDEX_PUBLIC_WITHDRAWAL, RELAY_SIGNAL_INDEX_PUBLIC_WITHDRAWAL_ASSET_HI, RELAY_SIGNAL_INDEX_PUBLIC_WITHDRAWAL_ASSET_LO, RELAY_SIGNAL_INDEX_STATE_ROOT, RELAY_SIGNAL_INDEX_WITHDRAW_ADDRESS_HI, RELAY_SIGNAL_INDEX_WITHDRAW_ADDRESS_LO, RELAY_TRANSACT_FIELD_BYTES, RELAY_TRANSACT_PACKAGE_VERSION_V1, RELAY_TRANSACT_SIGNAL_PREFIX_BYTES, RELAY_TRANSACT_SUPPORTED_SIGNAL_COUNT, type ReconstructedEscrowNote, type RelayKeyVersionHints, type RelayTransactPackageV1, type RelayTransactPackageVersion, type RelayTransactPublicLegContext, type RelayTransactSupportedProfile, type RequestKytPassageForPoolInteractionInput, type RequiredSubmissionMethodResult, SIX_BY_SIX_BINDING_ZK_NONCE, SIX_BY_SIX_ZK_NONCE, STANDARD_ZK_CONFIG_NONCE, SUBMISSION_METHOD, type StellarAddress, type StellarAsset, type StellarAssetId, type StellarAssetsCatalog, type StellarAvailablePrivateRecordsFilter, type StellarBrowserAssets, type StellarBrowserPrivacyClientConfig, type StellarBundledZkCircuitDefinition, type StellarCustomZkCircuitDefinition, type StellarDeliverySyncState, type StellarIncomingDeliveriesFilter, type StellarIncomingDelivery, type StellarKytEnvironment, type StellarLeafEphemeral, type StellarNetworkConfig, type StellarOperationReceipt, type StellarPolicyAdapter, type StellarPoolMerkleState, type StellarPreparedOperation, type StellarPrivacyClient, type StellarPrivacyClientConfig, type StellarPrivateAssetRow, type StellarPrivateRecord, type StellarPrivateRecordStatus, type StellarPublicBalance, type StellarPublicBalanceInput, type StellarRegistryLookup, type StellarStateAdapter, type StellarSubmissionPayload, type StellarTransactEngine, type StellarTransactEnvironment, type StellarTransactionDetails, type StellarTransactionStatus, type StellarTransferFromAddress, type StellarTransferIntent, type StellarZkCircuitDefinition, type SubmissionMethod, type TransferEscrowClaimantLimbs, type TransferEscrowSend, type TransferRecipientExecutionContext, type TransferTemporaryRecipientKey, ZERO_STROOPS, assertEscrowSweepClaimant, assetLegToTokenAddress, attachEscrowAuthorization, attachPoolStatePorts, buildBlindedRecipientTagChallengeMessage, buildPoolTransactionAuditParameters, buildPrivateAddressSignMessage, configurePrivacyPoolService, createDefaultTransactEngine, createPrivacyPoolService, createStellarPolicyAdapterFromEnvironment, createStellarPrivacyClient, createStellarPrivacyClientFromResolvedConfig, decodePrivateAddress, deriveEscrowRecipientFromStellarAddress, encodePrivateAddress, encodePrivateAddressFromHexCoordinates, evaluateRequiredSubmissionMethod, fetchAndMergeMerkleState, fetchEscrowOutputNoteEvents, finalizeSpendOperationAtExecute, frDecimalToPaddedBytes32, generateRandomDepositScalarHex, generateTemporaryRecipientPrivateAddress, getPrivacyPoolService, isEscrowPreparedOperation, isStellarPrivacyClient, listWalletPrivateAddressRecordsForOwnerFromStateSnapshot, listWalletPrivateAddressScalarsForOwnerFromStateSnapshot, loadDefaultStellarBrowserAssets, loadStellarBrowserAssets, optionalZkArtifactBaseUrl, parseAuditPublicKeyFromEnvHex, parseKytReasonCode, prepareConfidentialTransferProof, prepareConfidentialTransferProofDual, prepareEscrowSweepOperation, prepareRelayTransactPackage, prepareRelayTransactPackageFromPrepared, privateAddressSdk, readLeafEphemeralHex, readPrivateRecordsFromStateSnapshot, readRelayTransactSupportedProfile, readWalletDefaultPrivateAddressNonceFromStateSnapshot, readWalletPrivateAddressRecordFromStateSnapshot, readWalletPrivateAddressScalarFromStateSnapshot, recipientPublicKeysDecimalFromPrivateAddress, reconstructEscrowNote, requestKytPassageForPoolInteraction, requiredSubmissionMethod, resolvePoolApplicationId, resolveStellarPrivacyClientConfig, resolveZkConfigNonce, runTtlPreflight, stellarStateDefinitions, submitSorobanConfidentialTransfer, submitSorobanDeposit, tokenAddressToAssetLeg, unsignedEscrowAuthorizationForSweep };