@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/index.js

@@ -0,0 +1,216 @@
+/**
+ * UTXOpia SDK v3.0 (JoinSplit Architecture)
+ *
+ * Complete client library for interacting with the UTXOpia protocol.
+ * Private Bitcoin using ZK proofs.
+ *
+ * Networks: Solana deployments + Bitcoin testnet4/regtest/mainnet
+ *
+ * ## Quick Start
+ * ```typescript
+ * import { createNonInteractiveDeposit, generateJoinSplitProof, buildTransactInstruction } from '@utxopia/sdk';
+ *
+ * // 1. DEPOSIT: Generate BTC address + compact OP_RETURN payload.
+ * const deposit = await createNonInteractiveDeposit(meta, custodyInternalKey, 'testnet', undefined, opReturnContext);
+ * console.log('Send BTC to:', deposit.btcAddress);
+ *
+ * // 2. TRANSACT: JoinSplit proof for private transfer
+ * const proof = await generateJoinSplitProof(inputs);
+ *
+ * // 3. BUILD: Create Solana instruction
+ * const ix = buildTransactInstruction(options);
+ * ```
+ */
+// ==========================================================================
+// Cryptographic utilities
+// ==========================================================================
+export { 
+// Byte conversion (encoding utilities)
+bigintToBytes, bytesToBigint, hexToBytes, bytesToHex, 
+// Hashing
+sha256Hash, x25519Ecdh, ed25519GenerateKeyPair, ed25519PubToX25519, ed25519PrivToX25519, x25519PubFromPriv, x25519EcdhRaw, encryptAmountEd25519, decryptAmountEd25519, 
+// Low-level crypto (needed by E2E test scripts + contract deploy scripts)
+randomFieldElement, BN254_FIELD_PRIME, babyJubMul, BABYJUB_BASE8, } from "./crypto";
+// ==========================================================================
+// Key derivation (Solana wallet -> spending/viewing keys)
+// ==========================================================================
+export { 
+// Key derivation (high-level)
+deriveKeysFromWallet, deriveKeysFromSeed, deriveKeysFromSeedCircuit, deriveKeysFromAuthSignature, setupKeysFromAuthSignature, generateRandomAuthSignature, 
+// Key setup (combined derivation + stealth address)
+setupKeysFromWallet, setupKeysFromSeed, recreateStealthAddress, 
+// EdDSA signing
+eddsaPoseidonSign, eddsaPoseidonSignWithScalar, eddsaGetPrivScalar, eddsaGetPubKey, 
+// Stealth meta address
+createStealthMetaAddress, serializeStealthMetaAddress, deserializeStealthMetaAddress, encodeStealthMetaAddress, decodeStealthMetaAddress, 
+// Key lifecycle
+clearUTXOpiaKeys, 
+// Key serialization
+serializeKeysForStorage, deserializeKeysFromStorage, PASSKEY_CHAIN_SCOPE_DOMAIN, deriveChainScopedPasskeySeed, passkeyStorageOwner, } from "./keys";
+// Delegated viewing keys + auditor toolkit (Phase 1)
+export { ViewPermissions, hasPermission, isDelegatedKeyValid, isSlotInDelegatedRange, createDelegatedViewKey, serializeDelegatedViewKey, deserializeDelegatedViewKey, makeDelegationRecord, fingerprintDelegatedKey, clearDelegatedViewKey, 
+// The delegation-safe alternative: unlike createDelegatedViewKey this omits nullifyingKey,
+// which is what stops the holder from deriving every nullifier the account will ever publish.
+// It was reachable only by deep import while the footgun sat in the barrel.
+extractViewOnlyBundle, } from "./keys";
+export { auditScan, auditScanCiphertexts, auditRecordsToCsv, } from "./auditor";
+// Auditor ciphertext (Method-Y permissioned pool)
+export { encryptAuditorCiphertext, decryptAuditorCiphertext, buildAuditorCiphertextForNote, resolveAuditorCiphertext, AUDITOR_CIPHERTEXT_BYTES, } from "./auditor-ciphertext";
+export { generateAuditorViewingKeypair, deriveAuditorViewingKeypair, } from "./keys";
+// Sender memo channel (Phase 2)
+export { encryptSenderMemo, decryptSenderMemo, deriveOutgoingViewingKey, packSenderMemo, unpackSenderMemo, packSenderMemoForInstruction, buildSenderMemosForTransact, generateSenderMemoNonce, SENDER_MEMO_AMOUNT_BYTES, SENDER_MEMO_CIPHERTEXT_BYTES, SENDER_MEMO_COMMITMENT_BYTES, SENDER_MEMO_NONCE_BYTES, SENDER_MEMO_PACKED_BYTES, SENDER_MEMO_TAG_BYTES, SENDER_MEMO_TOKEN_BYTES, } from "./sender-memo";
+// Selective ZK disclosure proofs (Phase 4)
+export { generateOwnershipProof, generateRangeSumProof, computeRangeSumAttestation, pickRangeSumVariant, RANGE_SUM_N, RANGE_SUM_VARIANTS, RANGE_SUM_SIZES, } from "./selective-disclosure";
+// ==========================================================================
+// Deliberately not re-exported: isWalletAdapter, isDirectVaultDepositMode (guards the SDK
+// branches on), updateNoteWithHashes, updateStealthNoteWithHashes (mutators for fields the
+// SDK computes) and stealthNoteHasComputedHashes (a predicate over state no caller builds).
+// Still exported from their own modules for internal use — they are just not public API.
+// Poseidon hash utilities
+// ==========================================================================
+export { initPoseidon, isPoseidonReady, poseidonHashSync, computeUnifiedCommitmentSync, computeNullifierSync, hashNullifierSync, 
+// JoinSplit primitives (used by E2E scripts + pay-flow)
+computeMPKSync, computeNPKSync, computeJoinSplitCommitmentSync, computeJoinSplitNullifierSync, 
+// Multi-token
+computeTokenId, reduceToField, } from "./poseidon";
+// ==========================================================================
+// Token Registry (multi-token support)
+// ==========================================================================
+export { fetchTokenConfig, getTokenId, fetchSupportedTokens, fetchEnabledTokens, parseTokenConfig, } from "./token-registry";
+// ==========================================================================
+// MagicBlock ER / PER execution domains
+// ==========================================================================
+export { MAGICBLOCK_DELEGATION_PROGRAM_ID, MAGICBLOCK_DEVNET_ROUTER_URL, MAGICBLOCK_DEVNET_ROUTER_WS_URL, MAGICBLOCK_EPHEMERAL_VAULT_ID, MAGICBLOCK_MAGIC_CONTEXT_ID, MAGICBLOCK_MAGIC_PROGRAM_ID, MAGICBLOCK_MAX_PER_MEMBERS, MAGICBLOCK_PERMISSION_PROGRAM_ID, MAGICBLOCK_PER_MEMBER_FLAGS, MAGICBLOCK_VALIDATOR_IDENTITIES, buildDefaultPrivacyDomain, buildMagicBlockPerMemberFlags, deriveMagicBlockCommitRecordPDA, deriveMagicBlockCommitStatePDA, deriveMagicBlockDelegateBufferPDA, deriveMagicBlockDelegationMetadataPDA, deriveMagicBlockDelegationRecordPDA, deriveMagicBlockPermissionPDA, deriveMagicBlockUndelegateBufferPDA, requiresMagicBlockEndpoint, getMagicBlockEndpoint, getMagicBlockValidatorIdentity, createMagicBlockRouterConnection, } from "./magicblock";
+// ==========================================================================
+// Note (shielded commitment) utilities
+// ==========================================================================
+export { generateNote, createNoteFromSecrets, serializeNote, deserializeNote, noteHasComputedHashes, getNotePublicKeyX, computeNoteCommitment, computeNoteNullifier, formatBtc, parseBtc, deriveNote, deriveNotes, deriveMasterKey, deriveNoteFromMaster, estimateSeedStrength, createNote, prepareWithdrawal, createStealthNote, serializeStealthNote, deserializeStealthNote, 
+// JoinSplit note types
+createJoinSplitNote, computeJoinSplitNoteNullifier, serializeJoinSplitNote, deserializeJoinSplitNote, } from "./note";
+// ==========================================================================
+// Merkle tree utilities
+// ==========================================================================
+export { createMerkleProof, createMerkleProofFromBigints, proofToCircomFormat, proofToOnChainFormat, createEmptyMerkleProof, leafIndexToPathIndices, pathIndicesToLeafIndex, validateMerkleProofStructure, parseMerkleProofResponse, TREE_DEPTH, ROOT_HISTORY_SIZE, MAX_LEAVES, ZERO_VALUE, } from "./merkle";
+// ==========================================================================
+// Taproot address utilities
+// ==========================================================================
+export { deriveTaprootAddress, deriveTaprootAddressWithRefund, buildRefundScript, computeTapLeafHash, verifyTaprootAddress, createP2TRScriptPubkey, parseP2TRScriptPubkey, isValidBitcoinAddress, getInternalKey, createCustomInternalKey, createOpReturnScriptFromPayload, buildDepositOpReturn, parseDepositOpReturn, encodeDepositOpReturnHeader, decodeDepositOpReturnHeader, validateDepositOpReturnContext, computeDepositPoolTag, DEPOSIT_DESTINATION_CHAIN, DEPOSIT_BITCOIN_NETWORK, DEPOSIT_OP_RETURN_VERSION, DEPOSIT_POOL_TAG_SIZE, DEPOSIT_OP_RETURN_SIZE, } from "./taproot";
+// ==========================================================================
+// Claim link utilities
+// ==========================================================================
+export { encodeClaimLink, decodeClaimLink, parseClaimUrl, } from "./claim-link";
+// ==========================================================================
+// ChadBuffer utilities (for large proof uploads)
+// ==========================================================================
+export { uploadTransactionToBuffer, uploadProofToBuffer, closeBuffer, readBufferData, fetchRawTransaction, fetchMerkleProof, prepareVerifyDeposit, buildMerkleProof, needsBuffer as bufferNeedsBuffer, getProofSource, calculateUploadTransactions, CHADBUFFER_PROGRAM_ID, AUTHORITY_SIZE, MAX_DATA_PER_WRITE, SOLANA_TX_SIZE_LIMIT, } from "./chadbuffer";
+// ==========================================================================
+// Bound Parameters (JoinSplit transaction binding)
+// ==========================================================================
+export { computeBoundParamsHash, computeSolanaDomainBoundParamsHash, computeSolanaDomainSeparator, computeStealthDataHash, createTransferBoundParams, createUnshieldBoundParams, createRedeemBoundParams, SOLANA_BOUND_CHAIN_ID, SOLANA_DEVNET_BOUND_CHAIN_ID, SOLANA_MAINNET_BOUND_CHAIN_ID, DEFAULT_BOUND_PARAMS, } from "./bound-params";
+// ==========================================================================
+// Configuration
+// ==========================================================================
+export { getConfig, setConfig, createConfig, initConfig, DEVNET_CONFIG, MAINNET_CONFIG, LOCALNET_CONFIG, TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, ATA_PROGRAM_ID, UTXOPIA_POLICY_PROGRAM_ID, SDK_VERSION, DEPLOYMENT_INFO, JOINSPLIT_TREE_DEPTH, } from "./config";
+// ==========================================================================
+// PoolState account layout + fee arithmetic
+// ==========================================================================
+export { POOL_STATE_DISCRIMINATOR, POOL_STATE_LEN, POOL_STATE_OFFSETS, POOL_FLAG, parsePoolState, parsePoolFees, BPS_DENOMINATOR, computeBpsFee, feeShareBps, } from "./pool-state";
+// ==========================================================================
+// PDA Derivation
+// ==========================================================================
+export { PDA_SEEDS, 
+// Seed builders — the single definition of every PDA. Consumers on
+// @solana/web3.js should derive from these with findProgramAddressSync rather
+// than restating the seeds, which is how copies drift from the program.
+poolStateSeeds, commitmentTreeSeeds, tokenConfigSeeds, poolConfigSeeds, nullifierRecordSeeds, redemptionRequestSeeds, vkRegistrySeeds, depositReceiptSeeds, policyApprovalSeeds, exitDestinationSeeds, lightClientSeeds, blockHeaderSeeds, heightIndexSeeds, verifiedTransactionSeeds, derivePoolStatePDA, deriveCommitmentTreePDA, deriveNullifierRecordPDA, derivePolicyApprovalPDA, deriveExitDestinationPDA, EXIT_KIND_SOLANA_OWNER, EXIT_KIND_BTC_SCRIPT, deriveLightClientPDA, deriveBlockHeaderPDA, deriveHeightIndexPDA, deriveVkRegistryPDA, deriveRedemptionRequestPDA, deriveTokenConfigPDA, derivePoolConfigPDA, deriveDepositReceiptPDA, commitmentToBytes, } from "./pda";
+// ==========================================================================
+// Stealth address utilities
+// ==========================================================================
+export { createStealthDeposit, createStealthDepositWithKeys, createStealthOutput, createStealthOutputWithKeys, createStealthOutputForCommitment, packStealthOutputForCircuit, scanAnnouncements, scanAnnouncementsViewOnly, scanAnnouncementsViewOnlyMulti, exportViewOnlyKeys, encodeViewOnlyKeys, decodeViewOnlyKeys, prepareClaimInputs, scanUnifiedNotes, scanUnifiedNotesMulti, encryptAmount, decryptAmount, computeNullifierHashForNote, computeNullifierBytes, parseAnnouncementsFromHex, createDepositFromConfig, createDirectVaultDeposit, isDepositForViewer, isDepositForViewerHex, ANNOUNCEMENT_TYPE_DEPOSIT, ANNOUNCEMENT_TYPE_TRANSFER, createNonInteractiveDeposit, pickIkaCustodyKey, } from "./stealth";
+// ==========================================================================
+// PSBT builder for wallet-integrated deposits
+// ==========================================================================
+export { buildDepositPsbt, estimateDepositFee, fetchUtxos, selectUtxos, } from "./psbt";
+// ==========================================================================
+// Core utilities
+// ==========================================================================
+export { EsploraClient, esploraTestnet, esploraMainnet, } from "./core/esplora";
+// Mempool.space client with SPV support
+export { MempoolClient, mempoolTestnet, mempoolMainnet, reverseBytes, } from "./core/mempool";
+// ==========================================================================
+// Priority Fee Estimation
+// ==========================================================================
+export { estimatePriorityFee, buildPriorityFeeInstructionData, encodeSetComputeUnitLimit, encodeSetComputeUnitPrice, getHeliusRpcUrl, DEFAULT_COMPUTE_UNITS, DEFAULT_PRIORITY_FEE, COMPUTE_BUDGET_DISCRIMINATORS, } from "./solana/priority-fee";
+// ==========================================================================
+// Debug Logging
+// ==========================================================================
+export { setDebug } from "./logger";
+// ==========================================================================
+// Connection Adapter Factory
+// ==========================================================================
+export { createFetchConnectionAdapter, createConnectionAdapterFromWeb3, createConnectionAdapterFromKit, getConnectionAdapter, clearConnectionAdapterCache, } from "./solana/connection";
+// ==========================================================================
+// SNS Subdomain Resolver (*.utxopia.sol stealth addresses)
+// ==========================================================================
+export { resolveSnsName, resolveStealthName, parseSnsStealthData, isSnsStealthAddress, isAuditorDisclosable, SnsComplianceFlags, SNS_COMPLIANCE_AUDITOR_OFFSET, SNS_COMPLIANCE_AUDITOR_BYTES, deriveParentDomainKey, SNS_STEALTH_DATA_SIZE, } from "./sns-resolver";
+// ==========================================================================
+// Commitment Tree
+// ==========================================================================
+export { COMMITMENT_TREE_DISCRIMINATOR, parseCommitmentTreeData, isValidRoot, fetchCommitmentTree, getCommitmentIndex, saveCommitmentIndex, CommitmentTreeIndex, 
+// On-chain fetch functions (Helius-compatible)
+buildCommitmentTreeFromChain, fetchLeafIndexForCommitment, fetchMerkleProofForCommitment, getMerkleProofFromTree, } from "./commitment-tree";
+// ==========================================================================
+// Low-level Instruction Builders (JoinSplit only)
+// ==========================================================================
+export { INSTRUCTION_DISCRIMINATORS, 
+// Shield instruction
+buildShieldInstructionData, buildShieldInstruction, buildApproveRedemptionSigningInstructionData, buildApproveRedemptionSigningInstruction, 
+// Cancel redemption instruction
+buildCancelRedemptionInstructionData, buildCancelRedemptionInstruction, bigintTo32Bytes, bytes32ToBigint, 
+// JoinSplit transact instruction
+buildTransactInstructionData, buildTransactInstruction, 
+// JoinSplit + BTC redeem instruction
+buildRedeemInstructionData, 
+// Public unshield instruction
+buildUnshieldInstructionData, buildUnshieldInstruction, 
+// Timelocked pool update instructions
+buildProposePoolUpdateInstructionData, buildProposePoolUpdateInstruction, buildExecutePoolUpdateInstructionData, buildExecutePoolUpdateInstruction, buildCancelPoolUpdateInstructionData, buildCancelPoolUpdateInstruction, 
+// Rotate tree
+buildRotateTreeInstructionData, buildRotateTreeInstruction, 
+// MagicBlock lifecycle
+buildMagicBlockDelegateInstructionData, buildMagicBlockDelegateInstruction, buildMagicBlockCommitInstructionData, buildMagicBlockCommitInstruction, buildMagicBlockPerPermissionInstructionData, buildMagicBlockPerPermissionInstruction, buildPolicyRequestHash, buildPolicyIntentParts, buildRegisterExitDestinationInstruction, buildRegisterExitDestinationInstructionData, MAX_POLICY_INTENT_PARTS, buildInitializePolicyApprovalInstructionData, buildInitializePolicyApprovalInstruction, buildPolicyApprovalDecisionInstruction, buildPolicyApprovalCommitInstruction, buildCompleteDepositPermissionedInstructionData, buildCompleteDepositPermissionedInstruction, buildShieldPermissionedInstructionData, buildShieldPermissionedInstruction, buildRotateAuditorInstructionData, buildRotateAuditorInstruction, 
+// Verify instruction data builders
+buildVerifyTransactionInstructionData, buildCompleteDepositInstructionData, 
+// Pool config (disc 2) builder + parser
+buildSetPoolConfigInstructionData, parsePoolConfig, POOL_CONFIG_DISCRIMINATOR, POOL_CONFIG_LEN, POOL_SCRIPT_MAX_LEN, } from "./instructions";
+// ==========================================================================
+// VK Registry (JoinSplit Groth16 on-chain verification keys)
+// ==========================================================================
+export { VK_REGISTRY_DISCRIMINATOR, VK_REGISTRY_LEN, MAX_IC_POINTS, MAX_SAFE_JOINSPLIT_SIZE, INIT_VK_REGISTRY_DISCRIMINATOR, UPDATE_VK_REGISTRY_DISCRIMINATOR, joinSplitNumPublicInputs, computeVkHash, vkeyJsonToVkMaterial, buildVkRegistryData, parseVkRegistry, assertVkRegistryForShape, isVkRegistryReady, } from "./vk-registry";
+// ==========================================================================
+// ChadBuffer Relay
+// ==========================================================================
+// relay.ts held a second implementation of the ChadBuffer lifecycle — create / upload / close —
+// alongside chadbuffer.ts, which already does all three. Nothing imported it but this barrel, and
+// the two disagreed on chunk size (1020 vs 1056 bytes for the same write instruction), so one of
+// them was wrong. Removed; chadbuffer.ts is the single implementation.
+// ==========================================================================
+// Explorer (on-chain account fetchers & parsers)
+// ==========================================================================
+export { fetchExplorerDeposits, fetchExplorerTransfers, fetchExplorerRedemptions, parseNullifierRecord, parseRedemptionRequest, NULLIFIER_RECORD_SIZE, REDEMPTION_REQUEST_SIZE, NULLIFIER_RECORD_DISCRIMINATOR, REDEMPTION_REQUEST_DISCRIMINATOR, OPERATION_TYPE_LABELS, } from "./explorer";
+// ==========================================================================
+// Event Parsing (sol_log_data events from on-chain program)
+// ==========================================================================
+export { parseProgramEvents, parseNullifierSpentEvent, parseStealthAnnouncementEvent, parseSenderMemoEvent, parseBtcOriginAttestationEvent, parseAuditorCiphertextEvent, EVENT_NULLIFIER_SPENT, EVENT_STEALTH_ANNOUNCEMENT, EVENT_NULLIFIERS_BATCH, EVENT_ANNOUNCEMENTS_BATCH, EVENT_SENDER_MEMO, EVENT_BTC_ORIGIN_ATTESTATION, EVENT_AUDITOR_CIPHERTEXT, } from "./events";
+// ==========================================================================
+// Announcement Client (WS + REST + RPC fallback)
+// ==========================================================================
+export { AnnouncementClient, } from "./announcement-client";
+// ==========================================================================
+// Event Client (unified WS + REST for all event types)
+// ==========================================================================
+export { EventClient, } from "./event-client";
+// ==========================================================================
+// High-Level Client (Phase 1: init + auth + balance)
+// ==========================================================================
+export { UTXOpiaClient, } from "./client";