@arcanetech/privacy-sdk-stellar 0.5.4 → 0.6.1

package/dist/index.d.ts

@@ -64,6 +64,11 @@ interface StellarWalletPrivateAddressRecord {
     privateAddress: string;
     createdAt: number;
 }
+interface StellarLeanImtNode {
+    level: number;
+    index: number;
+    value: string;
+}
 interface StellarPoolMerkleState {
     poolContract: string;
     commitments: string[];
@@ -71,6 +76,7 @@ interface StellarPoolMerkleState {
     merkleRootHex: string;
     updatedAt: number;
     syncedLedger?: number;
+    nodes?: StellarLeanImtNode[];
 }
 interface StellarLeafEphemeral {
     poolContract: string;
@@ -176,6 +182,12 @@ interface LeafEphemeralStatePort {
     }): Promise<StellarLeafEphemeral | undefined>;
     set(ephemeral: StellarLeafEphemeral): Promise<void>;
 }
+interface CachedPoolMerkleView {
+    commitments: string[];
+    updatedAt: number;
+    merkleRootHex?: string;
+    nodes?: StellarLeanImtNode[];
+}
 
 type StellarSignTransaction = (input: {
     xdr: string;
@@ -364,29 +376,15 @@ interface FetchContractMerkleResult {
     commitments: string[];
     merkleRootHex: string;
     updatedAt: number;
+    nodes?: StellarLeanImtNode[];
 }
-/**
- * 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: {
+declare function persistFetchedMerkleState(input: {
     poolContractId: string;
-    walletPublicKey: string;
-    transactEnvironment: StellarTransactEnvironment;
+    commitments: string[];
+    merkleRootHex: string;
+    cachedState: CachedPoolMerkleView | undefined;
     poolMerkleState?: PoolMerkleStatePort;
 }): Promise<FetchContractMerkleResult>;
-declare function readLeafEphemeralHex(parameters: {
-    poolContractId: string;
-    walletPublicKey: string;
-    leafIndex: number;
-    transactEnvironment: StellarTransactEnvironment;
-    leafEphemeral?: LeafEphemeralStatePort;
-}): Promise<{
-    xHex: string;
-    yHex: string;
-}>;
 
 type StellarTransactionDetails = {
     txHash: string;
@@ -440,6 +438,7 @@ declare function composeStellarPrivacyClient(config: ResolvedStellarPrivacyClien
             commitments: string[];
             merkleRootHex: string;
             syncedLedger?: number;
+            nodes?: StellarPoolMerkleState["nodes"];
         }): Promise<void>;
         getWalletPrivateAddressRecord(input: {
             owner: StellarAddress;
@@ -620,6 +619,7 @@ declare function composeStellarStateService(adapter: StateBridgeAdapter): {
         commitments: string[];
         merkleRootHex: string;
         syncedLedger?: number;
+        nodes?: StellarPoolMerkleState["nodes"];
     }): Promise<void>;
     getWalletPrivateAddressRecord(input: {
         owner: StellarAddress;
@@ -721,6 +721,18 @@ declare function createStateDelegates(state: StellarStateService): {
 };
 type StellarPrivacyClientStateDelegates = ReturnType<typeof createStateDelegates>;
 
+type StellarPrivacyStateHydration = {
+    poolMerkleStates?: StellarPoolMerkleState[];
+    privateRecords?: StellarPrivateRecord[];
+    walletPrivateAddressRecords?: StellarWalletPrivateAddressRecord[];
+    walletPrivateAddressScalars?: StellarWalletPrivateAddressScalar[];
+    walletDefaultPrivateAddressNonces?: Array<{
+        owner: string;
+        nonce: string;
+    }>;
+    assets?: StellarAsset[];
+};
+
 type StellarPrivacyClientNetwork = ComposedStellarPrivacyClient['network'];
 type StellarPrivacyClientOperations = ComposedStellarPrivacyClient['operations'];
 type StellarPrivacyClient = {
@@ -738,7 +750,9 @@ type StellarPrivacyClient = {
     waitForTransactionConfirmation: StellarPrivacyClientNetwork['waitForTransactionConfirmation'];
     fetchTransactionConfirmationStatus: StellarPrivacyClientNetwork['fetchTransactionConfirmationStatus'];
     getTransactionDetails: StellarPrivacyClientNetwork['getTransactionDetails'];
-} & StellarPrivacyClientStateDelegates;
+} & StellarPrivacyClientStateDelegates & {
+    hydrateState: (snapshot: StellarPrivacyStateHydration) => Promise<void>;
+};
 
 type CreateStellarPrivacyClientResult = StellarPrivacyClient | ReturnType<typeof createRejectedOperation>;
 declare function isStellarPrivacyClient(result: CreateStellarPrivacyClientResult): result is StellarPrivacyClient;
@@ -1096,6 +1110,29 @@ type PrepareConfidentialTransferProofResult = {
 };
 declare function prepareConfidentialTransferProof(parameters: PrepareConfidentialTransferProofParameters): Promise<PrepareConfidentialTransferProofResult>;
 
+/**
+ * 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;
+    transactEnvironment: StellarTransactEnvironment;
+    poolMerkleState?: PoolMerkleStatePort;
+}): Promise<Awaited<ReturnType<typeof persistFetchedMerkleState>>>;
+declare function readLeafEphemeralHex(parameters: {
+    poolContractId: string;
+    walletPublicKey: string;
+    leafIndex: number;
+    transactEnvironment: StellarTransactEnvironment;
+    leafEphemeral?: LeafEphemeralStatePort;
+}): Promise<{
+    xHex: string;
+    yHex: string;
+}>;
+
 interface DecryptedKytAuditSlot {
     slot: number;
     decryptOk: boolean;
@@ -1231,4 +1268,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, 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 };
+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 StellarLeanImtNode, type StellarNetworkConfig, type StellarOperationReceipt, type StellarPolicyAdapter, type StellarPoolMerkleState, type StellarPreparedOperation, type StellarPrivacyClient, type StellarPrivacyClientConfig, type StellarPrivacyStateHydration, 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 };