@perena/vault-sdk 1.0.43 → 1.0.46

package/dist/browser/nest.d.mts

@@ -0,0 +1,208 @@
+import { Connection, PublicKey, Transaction, SimulatedTransactionResponse, TransactionInstruction, AddressLookupTableAccount } from '@solana/web3.js';
+import { Instruction, Address } from '@solana/kit';
+
+interface NestApiOptions {
+    baseUrl?: string;
+    fetchFn?: typeof fetch;
+    signal?: AbortSignal;
+}
+interface NestRedemptionQuote {
+    nestVaultSlug: string;
+    redemptionAsset: "USDC";
+    shareAmount: string;
+    shareDecimals: number;
+    redemptionAmount: string;
+    redemptionDecimals: number;
+    feeAmount: string;
+}
+interface NestRedemptionStep {
+    status: string;
+    statusCode?: number;
+    signature?: string;
+    amount?: string;
+    usdcClaimed?: string;
+    error?: string;
+}
+interface NestRedemptionStatus {
+    solanaBurnSignature: string;
+    solanaWallet: string;
+    overallStatus: string;
+    progress?: string;
+    steps: {
+        solanaBurn: NestRedemptionStep;
+        plumeProcessing: NestRedemptionStep;
+        cctpAttestation: NestRedemptionStep;
+        solanaClaim: NestRedemptionStep;
+    };
+    error?: {
+        code?: string;
+        message?: string;
+    };
+}
+declare class NestApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** Indicative quote only: the settlement price and fees may change in the queue. */
+declare function fetchNestRedemptionQuote(args: {
+    nestVaultSlug: string;
+    rawAmountNestToken: bigint;
+}, options?: NestApiOptions): Promise<NestRedemptionQuote>;
+/** Use the Squads EXECUTION signature, not the proposal-creation signature. */
+declare function fetchNestRedemptionStatus(signature: string, options?: NestApiOptions): Promise<NestRedemptionStatus | null>;
+
+interface TransactionPlan {
+    instructions: Instruction[];
+    lookupTables?: Address[];
+}
+
+interface VaultCacheInvalidation {
+    vaultPda: Address;
+    vaultOraclePda?: Address;
+    vaultTrancheStatePda?: Address;
+    withdrawalQueuePda?: Address;
+}
+interface VaultTransactionPlan extends TransactionPlan {
+    instructions: Instruction[];
+    postSuccessCacheInvalidations?: VaultCacheInvalidation[];
+}
+
+/**
+ * Build a standard nPERENA withdrawal from its current owner's ATA. The owner
+ * must already hold the shares; move program-held shares to the manager first.
+ * The returned plan can be proposed in Squads with the owner set to its vault PDA.
+ *
+ * Nest keepers settle the cross-chain withdrawal asynchronously and return USDC
+ * to the same owner. There is no user-signed Nest fulfillment transaction in the
+ * documented API. This plan deliberately does not append a premature redeposit.
+ */
+declare function buildNestWithdrawalRequest(args: {
+    connection: Connection;
+    owner: PublicKey;
+    rawAmountNestToken: bigint;
+    apiOptions?: NestApiOptions;
+}): Promise<VaultTransactionPlan>;
+/** Resolve ALTs before decompiling; reject additional signers Squads cannot supply. */
+declare function decodeNestWithdrawalRequest(args: {
+    connection: Connection;
+    owner: PublicKey;
+    rawAmountNestToken: bigint;
+    txBase64: string;
+}): Promise<VaultTransactionPlan>;
+
+/**
+ * {@link PriceSource} adapter over the `nest` package's price API, bound to the
+ * Perena vault's Nest slug and share mint.
+ */
+
+declare const NEST_VAULT_SLUG = "nest-perena-vault";
+declare const NEST_RWA_SHARE_MINT: Address;
+
+/**
+ * Maps a transaction-proposing wallet to the Squads vault it operates.
+ *
+ * The member wallet pays for and signs proposal creation. The derived Squads
+ * vault PDA is the authority that signs the instructions when the proposal is
+ * eventually executed.
+ */
+interface SquadsWalletRouteConfig {
+    wallet: string;
+    multisigPda: string;
+    vaultIndex: number;
+    memo?: string;
+}
+interface ResolvedSquadsWalletRoute {
+    wallet: PublicKey;
+    multisigPda: PublicKey;
+    vaultIndex: number;
+    vaultPda: PublicKey;
+    memo?: string;
+}
+interface PreparedDirectTransaction {
+    kind: "direct";
+    transaction: Transaction;
+    authority: PublicKey;
+}
+interface PreparedSquadsTransaction {
+    kind: "squads";
+    transaction: Transaction;
+    authority: PublicKey;
+    multisigPda: PublicKey;
+    vaultIndex: number;
+    transactionIndex: bigint;
+    proposalPda: PublicKey;
+    vaultTransactionPda: PublicKey;
+}
+type PreparedVaultTransaction = PreparedDirectTransaction | PreparedSquadsTransaction;
+type SquadsSimulationTransactionError = NonNullable<SimulatedTransactionResponse["err"]>;
+declare class SquadsProposalExecutionSimulationError extends Error {
+    readonly transactionError: SquadsSimulationTransactionError;
+    readonly logs: string[];
+    readonly unitsConsumed?: number;
+    constructor(transactionError: SquadsSimulationTransactionError, logs: readonly string[], unitsConsumed?: number);
+}
+/** Resolve and validate a configured wallet route, including its vault PDA. */
+declare function resolveSquadsWalletRoute(route: SquadsWalletRouteConfig): ResolvedSquadsWalletRoute;
+/** Find the optional Squads route for a connected proposer wallet. */
+declare function findSquadsWalletRoute(wallet: PublicKey | string, routes: readonly SquadsWalletRouteConfig[]): ResolvedSquadsWalletRoute | undefined;
+/** Fail fast on ambiguous wallet mappings or malformed route values. */
+declare function validateSquadsWalletRoutes(routes: readonly SquadsWalletRouteConfig[]): void;
+/**
+ * Return the authority that should be used while building vault instructions.
+ * For a configured member wallet this is the Squads vault PDA; otherwise it is
+ * the wallet itself.
+ */
+declare function vaultAuthorityForWallet(wallet: PublicKey | string, routes: readonly SquadsWalletRouteConfig[]): PublicKey;
+/**
+ * Simulate the instructions stored in a Squads proposal before creating it.
+ *
+ * Signature verification is intentionally disabled so the runtime treats the
+ * Squads vault PDA's signer account meta as signed, matching the privileges it
+ * receives from Squads' eventual `invoke_signed` execution. This validates the
+ * inner instructions against current chain state; it does not validate Squads
+ * approvals or the execution wrapper itself.
+ *
+ * Throws {@link SquadsProposalExecutionSimulationError} when the simulated
+ * instructions fail.
+ */
+declare function simulateSquadsProposalExecution(args: {
+    connection: Connection;
+    feePayer: PublicKey;
+    instructions: readonly TransactionInstruction[];
+    recentBlockhash?: string;
+    addressLookupTableAccounts?: AddressLookupTableAccount[];
+}): Promise<SimulatedTransactionResponse>;
+/**
+ * Build either a normal transaction or a Squads proposal-creation transaction,
+ * based on whether `proposer` has a configured wallet route.
+ *
+ * The returned Squads transaction creates both the vault transaction and its
+ * proposal. It does not approve or execute the proposal.
+ */
+declare function prepareVaultTransaction(args: {
+    connection: Connection;
+    proposer: PublicKey;
+    instructions: readonly TransactionInstruction[];
+    squadsRoutes?: readonly SquadsWalletRouteConfig[];
+    /** Skip execution simulation when proposing a transaction that depends on future funding. */
+    skipSimulation?: boolean;
+    addressLookupTableAccounts?: AddressLookupTableAccount[];
+}): Promise<PreparedVaultTransaction>;
+
+interface SquadsProposalUpload {
+    /** Send these sequentially, waiting for confirmation after each. */
+    setupTransactions: Transaction[];
+    /** Creates the proposal only after the entire message is stored. */
+    proposalTransaction: Transaction;
+    bufferPda?: PublicKey;
+    /** Explicit recovery if upload is interrupted. Never submit this automatically. */
+    closeBufferInstruction?: TransactionInstruction;
+}
+/** Large cross-chain messages need Squads' buffer upload even when execution uses ALTs. */
+declare function prepareSquadsProposalUpload(args: {
+    connection: Connection;
+    proposer: PublicKey;
+    prepared: PreparedSquadsTransaction;
+}): Promise<SquadsProposalUpload>;
+
+export { NEST_RWA_SHARE_MINT, NEST_VAULT_SLUG, NestApiError, type NestApiOptions, type NestRedemptionQuote, type NestRedemptionStatus, type PreparedDirectTransaction, type PreparedSquadsTransaction, type PreparedVaultTransaction, type ResolvedSquadsWalletRoute, SquadsProposalExecutionSimulationError, type SquadsProposalUpload, type SquadsWalletRouteConfig, buildNestWithdrawalRequest, decodeNestWithdrawalRequest, fetchNestRedemptionQuote, fetchNestRedemptionStatus, findSquadsWalletRoute, prepareSquadsProposalUpload, prepareVaultTransaction, resolveSquadsWalletRoute, simulateSquadsProposalExecution, validateSquadsWalletRoutes, vaultAuthorityForWallet };