@ercworldio/blockchain-shared 1.0.5-dev.7.PROJ-1464.0 → 1.0.5-dev.8

package/build/services/solana/escrow/services/EscrowAdminUtility.d.ts

@@ -3,10 +3,47 @@ import { Program } from "@coral-xyz/anchor";
 import { Commitment, Keypair, PublicKey, TransactionSignature } from "@solana/web3.js";
 import { Escrow } from "../types/escrow";
 import { BatchReceiver } from "../types/types";
+import { ChainId } from "../../../../interfaces";
 export declare class EscrowAdminUtility {
     program: Program<Escrow>;
     provider: anchor.AnchorProvider;
-    constructor(program: Program<Escrow>, provider: anchor.AnchorProvider);
+    /**
+     * Optional Address Lookup Table. When set, transactions are sent as v0 and the batch path's
+     * ~11 static accounts collapse from 32 bytes each to a 1-byte index — roughly 300 bytes back,
+     * which is what makes >2 treasury signatures fit under the 1232-byte limit.
+     */
+    private lookupTableAddress?;
+    private lookupTableCache?;
+    constructor(program: Program<Escrow>, provider: anchor.AnchorProvider, lookupTableAddress?: string);
+    /** Accounts that are identical on every batch withdrawal — the ALT payload. */
+    lookup_table_addresses(mints: string[]): PublicKey[];
+    /**
+     * Idempotently guarantees a lookup table covering `mints` exists and is usable.
+     *
+     * Deliberately keeps no external state: tables are discovered on-chain by their authority
+     * (the funding wallet), so there is nothing to persist, migrate, or keep in sync across
+     * environments and worker instances. Extends a table that is missing addresses, creates one
+     * when none exists, and returns the usable address.
+     *
+     * Returns null if provisioning fails — the lookup table is an optimisation, so callers fall
+     * back to legacy transactions rather than failing a withdrawal that would otherwise succeed.
+     */
+    ensure_lookup_table(mints: string[], signer?: Keypair): Promise<PublicKey>;
+    /** Back-compat wrapper for explicit one-time provisioning; prefer `ensure_lookup_table`. */
+    create_lookup_table(mints: string[], signer?: Keypair): Promise<string>;
+    private fetchLookupTable;
+    /**
+     * Finds a live table already owned by this authority. `getProgramAccounts` is filtered
+     * server-side on the authority pubkey, which sits at a fixed offset in the table header:
+     * u32 typeIndex + u64 deactivationSlot + u64 lastExtendedSlot + u8 startIndex + u8 option tag.
+     */
+    private discoverLookupTable;
+    private missingAddresses;
+    private createLookupTable;
+    private extendLookupTable;
+    private waitForLookupTableActivation;
+    /** Resolves (and caches) the configured lookup table; [] when none is set or it's missing. */
+    private resolveLookupTables;
     /**
      * Check if the escrow program is paused or running
      * @returns true/false. True: program is paused. False: Program is running
@@ -84,15 +121,89 @@ export declare class EscrowAdminUtility {
     /**
      *  Accepts an array of receivers and amounts and performs a batch withdrawal to the specified receivers
      * for the specified token (SOL or SPL)
+     * @param chain_id Network's chain id
      * @param token_address Address of the token to withdraw
      * @param recipients Array of receivers and their amounts
      * @param signer optional signer keypair
      * @returns string - signature
      */
-    withdraw_batch(token_address: string, recipients: BatchReceiver[], signer?: Keypair): Promise<string>;
+    withdraw_batch(chain_id: ChainId, token_address: string, recipients: BatchReceiver[], signer?: Keypair): Promise<string>;
+    /**
+     * Executes previously-scheduled (timelocked) withdrawals whose delay has elapsed. The amounts
+     * and recipient are read from each commitment on-chain, so only the request ids + their
+     * commitment/recipient accounts are supplied. Pays out and closes each commitment.
+     *
+     * Sent as a v0 transaction over the escrow lookup table: a batch's per-request accounts
+     * (commitment + recipient [+ ATA]) plus the static config accounts overflow a legacy
+     * transaction beyond a handful of requests, so we reuse the same ALT as the withdraw path.
+     */
+    batch_execute_withdrawal(chain_id: ChainId, token_address: string, receivers: Array<{
+        request_id: number;
+        receiver_pubkey: PublicKey | string;
+    }>, signer?: Keypair): Promise<string>;
+    /** Builds the SOL batch-execute instruction. Shared by the send and simulate paths. */
+    private build_batch_execute_sol_ixs;
+    /** Builds the SPL batch-execute instruction. Shared by the send and simulate paths. */
+    private build_batch_execute_spl_ixs;
+    private batch_execute_withdrawal_sol;
+    private batch_execute_withdrawal_spl;
+    /**
+     * Simulates a batch execute without sending, returning `{ ok, error }`. The funding worker
+     * uses it to quarantine requests that would revert (timelock not elapsed, commitment already
+     * executed, …) before committing the real batch — the program reverts the whole transaction
+     * without naming the offending request, so callers simulate one request at a time.
+     */
+    simulate_batch_execute_withdrawal(chain_id: ChainId, token_address: string, receivers: Array<{
+        request_id: number;
+        receiver_pubkey: PublicKey | string;
+    }>): Promise<{
+        ok: boolean;
+        error: string | null;
+    }>;
+    /**
+     * Builds an (unsigned) transaction from `ixs` and simulates it. Returns `{ ok:false, error }`
+     * with the revert reason from the program logs when it would fail. `sigVerify:false` skips the
+     * missing fee-payer signature; the Ed25519 program instruction still executes, so invalid or
+     * insufficient treasury signatures are caught here too.
+     */
+    private simulateInstructions;
+    /** Per-request PDAs the folded batch path expects: receiver timelock override + commitment. */
+    private request_pdas;
+    /** Matches the program's IDS_PER_PAGE — the replay-bitmap page a request id maps to. */
+    private static readonly IDS_PER_PAGE;
+    /**
+     * The distinct replay-bitmap page accounts a batch touches. The program appends these AFTER
+     * the per-request accounts and locates each request's page by key, so a page shared by several
+     * requests is passed once. Metas are writable (the program may create/flip bits) and non-signer.
+     */
+    private bitmap_page_accounts;
+    /**
+     * Builds the Ed25519SigVerify instruction the program scans to enforce treasury multisig.
+     * Each request contributes its signers' approvals over that request's message (which binds
+     * the committed amount + token + chain + request id). Returns null when no request carries
+     * signatures, so plain batches send just the withdraw instruction.
+     */
+    private buildBatchTreasuryEd25519;
+    /**
+     * Builds the instruction list for an SPL batch withdraw: an optional treasury Ed25519 proof
+     * followed by the batch instruction. Shared by the send and simulate paths so they never drift.
+     */
+    private build_batch_withdraw_spl_ixs;
     /** @dev this might fail if the recipient does not have an ATA - take care of it in funding worker task */
     private batch_withdraw_spl;
+    /** Builds the instruction list for a SOL batch withdraw (optional treasury proof + batch ix). */
+    private build_batch_withdraw_sol_ixs;
     private batch_withdraw_sol;
+    /**
+     * Simulates a batch withdraw without sending, returning `{ ok, error }`. Used by the funding
+     * worker to quarantine individual requests that would revert (bad/insufficient signatures,
+     * already scheduled, …) before committing the real batch — the program reverts the whole
+     * transaction without naming the offending request, so callers simulate one request at a time.
+     */
+    simulate_withdraw_batch(chain_id: ChainId, token_address: string, recipients: BatchReceiver[]): Promise<{
+        ok: boolean;
+        error: string | null;
+    }>;
     private withdraw_sol;
     private withdraw_spl;
     private deposit_sol;
@@ -100,6 +211,8 @@ export declare class EscrowAdminUtility {
     getVaultBalance(): Promise<number>;
     getVaultTokenBalance(mint: PublicKey): Promise<number>;
     private sendTransaction;
+    private sendVersionedTransaction;
+    private sendLegacyTransaction;
     confirmTransaction(signature: string, commitment?: Commitment): Promise<void>;
     waitForConfirmation(signature: TransactionSignature, commitment?: 'confirmed' | 'finalized', timeoutMs?: number): Promise<void>;
     /**
@@ -116,7 +229,7 @@ export declare class EscrowAdminUtility {
      * @param idl IDL file - Escrow program idl
      * @returns
      */
-    static createWithCustomProgramId(provider: anchor.AnchorProvider, programId: PublicKey, idl: anchor.Idl): EscrowAdminUtility;
+    static createWithCustomProgramId(provider: anchor.AnchorProvider, programId: PublicKey, idl: anchor.Idl, lookupTableAddress?: string): EscrowAdminUtility;
 }
 export default EscrowAdminUtility;
 //# sourceMappingURL=EscrowAdminUtility.d.ts.map

package/build/services/solana/escrow/services/EscrowAdminUtility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EscrowAdminUtility.d.ts","sourceRoot":"","sources":["../../../../../src/services/solana/escrow/services/EscrowAdminUtility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,OAAO,EAAoB,SAAS,EAA0E,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAGjL,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAKzC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,qBAAa,kBAAkB;IACpB,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC,cAAc,CAAC;gBAE3B,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,cAAc;IAWrE;;;OAGG;IACU,SAAS;IAYtB;;;;OAIG;IACU,QAAQ,CAAC,cAAc,EAAE,MAAM;IAgB5C;;;;OAIG;IACU,gBAAgB,CAAC,cAAc,EAAE,MAAM;IAgBvC,YAAY;IA6BzB;;;OAGG;IACU,kBAAkB;IAY/B;;;OAGG;IACU,UAAU;IAiBvB;;;;;OAKG;IACU,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAkCtD,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAmBtE;;;;;OAKG;IACU,SAAS,CAAC,iBAAiB,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAmBlE;;;;;OAKG;IACU,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAoBlE;;;;;OAKG;IACU,eAAe,CAAC,YAAY,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO;IAqBpE;;;;;;OAMG;IACU,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAUxF;;;;;;;OAOG;IACU,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAWnH;;;;;;;OAOG;IACU,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO;IAUhG,0GAA0G;YAC5F,kBAAkB;YAsClB,kBAAkB;YA2ClB,YAAY;YAyBZ,YAAY;YAgCZ,WAAW;YAwBX,WAAW;IAuCnB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAUlC,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;YAU9C,eAAe;IA0BhB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,GAAE,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1F,mBAAmB,CAC5B,SAAS,EAAE,oBAAoB,EAC/B,UAAU,GAAE,WAAW,GAAG,WAAyB,EACnD,SAAS,SAAS,GACnB,OAAO,CAAC,IAAI,CAAC;IAkChB;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,GAAG,kBAAkB;IAKnF;;;;;;OAMG;IACH,MAAM,CAAC,yBAAyB,CAAC,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,GAAG,kBAAkB;CAM/H;AAED,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"EscrowAdminUtility.d.ts","sourceRoot":"","sources":["../../../../../src/services/solana/escrow/services/EscrowAdminUtility.ts"],"names":[],"mappings":"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"}