@layerzerolabs/lz-solana-sdk-v2 3.0.47 → 3.0.48

package/src/utility.ts

@@ -0,0 +1,592 @@
+import crypto from 'crypto'
+
+import * as beet from '@metaplex-foundation/beet'
+import {
+    AddressLookupTableProgram,
+    Blockhash,
+    CloseLookupTableParams,
+    Commitment,
+    Connection,
+    DeactivateLookupTableParams,
+    Finality,
+    GetAccountInfoConfig,
+    GetVersionedTransactionConfig,
+    Keypair,
+    MessageV0,
+    NONCE_ACCOUNT_LENGTH,
+    NonceAccount,
+    PartiallyDecodedInstruction,
+    PublicKey,
+    SystemProgram,
+    Transaction,
+    TransactionInstruction,
+    TransactionMessage,
+    TransactionSignature,
+    VersionedTransaction,
+} from '@solana/web3.js'
+import base58 from 'bs58'
+
+import { sha2_256 } from '@layerzerolabs/lz-foundation'
+
+import { EventEmitDiscriminator } from './endpoint'
+import {
+    ComposeDeliveredEvent,
+    ComposeSentEvent,
+    PacketDeliveredEvent,
+    PacketSentEvent,
+    PacketVerifiedEvent,
+    composeDeliveredEventBeet,
+    composeSentEventBeet,
+    packetDeliveredEventBeet,
+    packetSentEventBeet,
+    packetVerifiedEventBeet,
+} from './generated/endpoint/events'
+import { FeesPaidEvent, feesPaidEventBeet } from './generated/uln/events'
+
+/**
+ * Gets the event discriminator for a given event.
+ *
+ * @param {string} event - The event name.
+ * @returns {string} The event discriminator.
+ */
+function getEventDiscriminator(event: string): string {
+    const hash = crypto.createHash('sha256')
+    /*
+        https://book.anchor-lang.com/anchor_bts/discriminator.html
+        sha256(namespace:eventName) namespace of cpi event is 'event'
+    */
+    hash.update(`event:${event}`)
+    const sha256 = hash.digest('hex')
+    return sha256.slice(0, 16) // first 8 bytes
+}
+
+/**
+ * Extracts the sent packet event by transaction hash.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} program - The program public key.
+ * @param {TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>} signature - The transaction signature or parsed transaction.
+ * @param {Finality | GetVersionedTransactionConfig} [commitment] - The commitment level.
+ * @param {boolean} [unsafeParseErr=false] - Whether to parse the event even if the transaction failed.
+ * @returns {Promise<PacketSentEvent[] | null>} A promise that resolves to an array of sent packet events or null if not found.
+ */
+export async function extractSentPacketEventByTxHash(
+    connection: Connection,
+    program: PublicKey,
+    signature: TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>,
+    commitment?: Finality | GetVersionedTransactionConfig,
+    unsafeParseErr = false
+): Promise<PacketSentEvent[] | null> {
+    const events = await extractEventFromTransactionSignature<PacketSentEvent>(
+        connection,
+        program,
+        signature,
+        packetSentEventBeet,
+        commitment,
+        unsafeParseErr
+    )
+    if (!events) return null
+    return events
+}
+
+/**
+ * Extracts the verified packet event by transaction hash.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} program - The program public key.
+ * @param {TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>} signature - The transaction signature or parsed transaction.
+ * @param {Finality | GetVersionedTransactionConfig} [commitment] - The commitment level.
+ * @param {boolean} [unsafeParseErr=false] - Whether to parse the event even if the transaction failed.
+ * @returns {Promise<PacketVerifiedEvent[] | null>} A promise that resolves to an array of verified packet events or null if not found.
+ */
+export async function extractVerifiedPacketEventByTxHash(
+    connection: Connection,
+    program: PublicKey,
+    signature: TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>,
+    commitment?: Finality | GetVersionedTransactionConfig,
+    unsafeParseErr = false
+): Promise<PacketVerifiedEvent[] | null> {
+    const events = await extractEventFromTransactionSignature<PacketVerifiedEvent>(
+        connection,
+        program,
+        signature,
+        packetVerifiedEventBeet,
+        commitment,
+        unsafeParseErr
+    )
+    if (!events) return null
+    return events
+}
+
+/**
+ * Extracts the received packet event by transaction hash.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} program - The program public key.
+ * @param {TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>} signature - The transaction signature or parsed transaction.
+ * @param {Finality | GetVersionedTransactionConfig} [commitment] - The commitment level.
+ * @param {boolean} [unsafeParseErr=false] - Whether to parse the event even if the transaction failed.
+ * @returns {Promise<PacketDeliveredEvent[] | null>} A promise that resolves to an array of received packet events or null if not found.
+ */
+export async function extractReceivedPacketEventByTxHash(
+    connection: Connection,
+    program: PublicKey,
+    signature: TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>,
+    commitment?: Finality | GetVersionedTransactionConfig,
+    unsafeParseErr = false
+): Promise<PacketDeliveredEvent[] | null> {
+    const events = await extractEventFromTransactionSignature<PacketDeliveredEvent>(
+        connection,
+        program,
+        signature,
+        packetDeliveredEventBeet,
+        commitment,
+        unsafeParseErr
+    )
+    if (!events) return null
+    return events
+}
+
+/**
+ * Extracts the compose sent event by transaction hash.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} program - The program public key.
+ * @param {TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>} signature - The transaction signature or parsed transaction.
+ * @param {Finality | GetVersionedTransactionConfig} [commitment] - The commitment level.
+ * @param {boolean} [unsafeParseErr=false] - Whether to parse the event even if the transaction failed.
+ * @returns {Promise<ComposeSentEvent[] | null>} A promise that resolves to an array of compose sent events or null if not found.
+ */
+export async function extractComposeSentEventByTxHash(
+    connection: Connection,
+    program: PublicKey,
+    signature: TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>,
+    commitment?: Finality | GetVersionedTransactionConfig,
+    unsafeParseErr = false
+): Promise<ComposeSentEvent[] | null> {
+    const events = await extractEventFromTransactionSignature<ComposeSentEvent>(
+        connection,
+        program,
+        signature,
+        composeSentEventBeet,
+        commitment,
+        unsafeParseErr
+    )
+    if (!events) return null
+    return events
+}
+
+/**
+ * Extracts the compose delivered event by transaction hash.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} program - The program public key.
+ * @param {TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>} signature - The transaction signature or parsed transaction.
+ * @param {Finality | GetVersionedTransactionConfig} [commitment] - The commitment level.
+ * @param {boolean} [unsafeParseErr=false] - Whether to parse the event even if the transaction failed.
+ * @returns {Promise<ComposeDeliveredEvent[] | null>} A promise that resolves to an array of compose delivered events or null if not found.
+ */
+export async function extractComposeDeliveredEventByTxHash(
+    connection: Connection,
+    program: PublicKey,
+    signature: TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>,
+    commitment?: Finality | GetVersionedTransactionConfig,
+    unsafeParseErr = false
+): Promise<ComposeDeliveredEvent[] | null> {
+    const events = await extractEventFromTransactionSignature<ComposeDeliveredEvent>(
+        connection,
+        program,
+        signature,
+        composeDeliveredEventBeet,
+        commitment,
+        unsafeParseErr
+    )
+    if (!events) return null
+    return events
+}
+
+/**
+ * Extracts the worker fee paid event by transaction hash.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} program - The program public key.
+ * @param {TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>} signature - The transaction signature or parsed transaction.
+ * @param {Finality | GetVersionedTransactionConfig} [commitment] - The commitment level.
+ * @param {boolean} [unsafeParseErr=false] - Whether to parse the event even if the transaction failed.
+ * @returns {Promise<FeesPaidEvent[] | null>} A promise that resolves to an array of worker fee paid events or null if not found.
+ */
+export async function extractWorkerFeePaidEventByTxHash(
+    connection: Connection,
+    program: PublicKey,
+    signature: TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>,
+    commitment?: Finality | GetVersionedTransactionConfig,
+    unsafeParseErr = false
+): Promise<FeesPaidEvent[] | null> {
+    const events = await extractEventFromTransactionSignature<FeesPaidEvent>(
+        connection,
+        program,
+        signature,
+        feesPaidEventBeet,
+        commitment,
+        unsafeParseErr
+    )
+    if (!events) return null
+    return events
+}
+
+/**
+ * Extracts events from a transaction signature.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} program - The program public key, extract event from specific program id
+ * @param {TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>} signature - The transaction signature(tx hash) or parsed transaction.
+ * @param {beet.FixableBeetArgsStruct<E> | beet.BeetArgsStruct<E>} eventBeet - The beet struct for the event.
+ * @param {Finality | GetVersionedTransactionConfig} [commitment] - The commitment level.
+ * @param {boolean} [unsafeParseErr=false] - Whether to parse the event even if the transaction failed. Default is false, only parse event if transaction succeeded. if true, will parse event even if transaction failed. Please set this to false if you want to ignore failed transaction and set `true` with caution as it may lead to unexpected behavior.
+ * @returns {Promise<E[] | null>} A promise that resolves to an array of events or null if not found.
+ */
+export async function extractEventFromTransactionSignature<E>(
+    connection: Connection,
+    program: PublicKey,
+    signature: TransactionSignature | Awaited<ReturnType<typeof connection.getParsedTransaction>>,
+    eventBeet: beet.FixableBeetArgsStruct<E> | beet.BeetArgsStruct<E>,
+    commitment?: Finality | GetVersionedTransactionConfig,
+    unsafeParseErr = false
+): Promise<E[] | null> {
+    const tx = typeof signature === 'string' ? await connection.getParsedTransaction(signature, commitment) : signature
+    if (tx == null) return null
+    const events = new Array<E>()
+    // refer: https://solana.com/docs/rpc/http/gettransaction
+    // tx.meta.err: Error if transaction failed, null if transaction succeeded
+    if (tx.meta?.err !== null && !unsafeParseErr) {
+        return null
+    }
+    for (const instruction of tx.meta?.innerInstructions ?? []) {
+        for (const innerInstruction of instruction.instructions) {
+            const inst = innerInstruction as PartiallyDecodedInstruction
+            if (!inst.programId.equals(program)) {
+                continue
+            }
+            const decoded = base58.decode(inst.data)
+            const discriminator = Buffer.from(decoded.subarray(0, 8)).toString('hex')
+            if (discriminator !== EventEmitDiscriminator) {
+                continue
+            }
+            // get second 8 bits, filter event here
+            const eventDiscriminator = Buffer.from(decoded.subarray(8, 16)).toString('hex')
+            if (eventDiscriminator !== getEventDiscriminator(eventBeet.description)) {
+                continue
+            }
+            const dataBuffer = Buffer.from(decoded.subarray(16, decoded.length))
+            if (eventBeet instanceof beet.FixableBeetArgsStruct) {
+                const beet = eventBeet.toFixedFromData(dataBuffer, 0)
+                events.push(beet.read(dataBuffer, 0))
+            } else {
+                events.push(eventBeet.read(dataBuffer, 0))
+            }
+        }
+    }
+    return events.length > 0 ? events : null
+}
+
+/**
+ * Generates an address lookup table.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} payer - The payer public key.
+ * @param {PublicKey} authority - The authority public key.
+ * @param {PublicKey[]} addresses - The addresses to include in the lookup table.
+ * @returns {Promise<{ instructions: TransactionInstruction[]; address: PublicKey }>} A promise that resolves to the instructions and lookup table address.
+ */
+export async function generateAddressLookupTable(
+    connection: Connection,
+    payer: PublicKey,
+    authority: PublicKey,
+    addresses: PublicKey[]
+): Promise<{ instructions: TransactionInstruction[]; address: PublicKey }> {
+    const slot = await connection.getSlot('finalized')
+    const [createInstruction, lookupTableAddress] = AddressLookupTableProgram.createLookupTable({
+        payer,
+        authority,
+        recentSlot: slot,
+    })
+    const extendInstruction = AddressLookupTableProgram.extendLookupTable({
+        payer,
+        authority,
+        lookupTable: lookupTableAddress,
+        addresses,
+    })
+
+    return {
+        instructions: [createInstruction, extendInstruction],
+        address: lookupTableAddress,
+    }
+}
+
+/**
+ * Deactivates an address lookup table.
+ * To properly terminate the lookup table, it is advisable to initially invoke `deactivateLookupTable`,
+ * pause for a duration of 500 blocks, and subsequently invoke `closeLookupTable`.
+ *
+ * @param {PublicKey} authority - The authority public key.
+ * @param {PublicKey} lookupTable - The lookup table public key.
+ * @returns {TransactionInstruction} The transaction instruction.
+ */
+export function deactivateLookupTable(authority: PublicKey, lookupTable: PublicKey): TransactionInstruction {
+    return AddressLookupTableProgram.deactivateLookupTable({
+        authority,
+        lookupTable,
+    } satisfies DeactivateLookupTableParams)
+}
+
+/**
+ * Closes an address lookup table.
+ * To properly terminate the lookup table, it is advisable to initially invoke `deactivateLookupTable`,
+ * pause for a duration of 500 blocks, and subsequently invoke `closeLookupTable`.
+ *
+ * @param {PublicKey} recipient - The recipient public key.
+ * @param {PublicKey} authority - The authority public key.
+ * @param {PublicKey} lookupTable - The lookup table public key.
+ * @returns {TransactionInstruction} The transaction instruction.
+ */
+export function closeLookupTable(
+    recipient: PublicKey,
+    authority: PublicKey,
+    lookupTable: PublicKey
+): TransactionInstruction {
+    return AddressLookupTableProgram.closeLookupTable({
+        authority,
+        recipient,
+        lookupTable,
+    } satisfies CloseLookupTableParams)
+}
+
+/**
+ * Creates a versioned transaction with an address lookup table.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} payer - The payer public key.
+ * @param {TransactionInstruction[]} instructions - The transaction instructions.
+ * @param {Blockhash} [recentBlockHash] - The recent block hash.
+ * @param {PublicKey} [tableAddr] - The address lookup table public key.
+ * @returns {Promise<VersionedTransaction>} A promise that resolves to the versioned transaction.
+ */
+export async function txWithAddressLookupTable(
+    connection: Connection,
+    payer: PublicKey,
+    instructions: TransactionInstruction[],
+    recentBlockHash?: Blockhash,
+    tableAddr?: PublicKey
+): Promise<VersionedTransaction> {
+    recentBlockHash = recentBlockHash ?? (await connection.getLatestBlockhash()).blockhash
+    if (!tableAddr) {
+        return new VersionedTransaction(
+            new TransactionMessage({
+                instructions,
+                payerKey: payer,
+                recentBlockhash: recentBlockHash,
+            }).compileToV0Message()
+        )
+    }
+    const { value: lookupTableAccount } = await connection.getAddressLookupTable(tableAddr)
+    return new VersionedTransaction(
+        new TransactionMessage({
+            instructions,
+            payerKey: payer,
+            recentBlockhash: recentBlockHash,
+        }).compileToV0Message(lookupTableAccount ? [lookupTableAccount] : undefined)
+    )
+}
+
+/**
+ * Creates a nonce account transaction.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} auth - The authorized public key.
+ * @param {number} [lamportsForRent] - The lamports for rent.
+ * @returns {Promise<{ tx: Transaction; nonceAccount: Keypair }>} A promise that resolves to the transaction and nonce account.
+ */
+export async function createNonceAccountTX(
+    connection: Connection,
+    auth: PublicKey,
+    lamportsForRent?: number
+): Promise<{ tx: Transaction; nonceAccount: Keypair }> {
+    const nonceAccount = Keypair.generate()
+
+    const lamports = lamportsForRent ?? (await connection.getMinimumBalanceForRentExemption(NONCE_ACCOUNT_LENGTH))
+
+    const tx = new Transaction()
+    tx.add(
+        // create nonce account
+        SystemProgram.createAccount({
+            fromPubkey: auth,
+            newAccountPubkey: nonceAccount.publicKey,
+            lamports,
+            space: NONCE_ACCOUNT_LENGTH,
+            programId: SystemProgram.programId,
+        }),
+        // init nonce account
+        SystemProgram.nonceInitialize({
+            noncePubkey: nonceAccount.publicKey, // nonce account pubkey
+            authorizedPubkey: auth, // nonce account auth
+        })
+    )
+    return { tx, nonceAccount }
+}
+
+/**
+ * Creates a transaction with a nonce.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} noncePubkey - The nonce public key.
+ * @param {TransactionInstruction[]} instructions - The transaction instructions.
+ * @param {NonceAccount} [nonceInfo] - The nonce account information.
+ * @returns {Promise<Transaction | null>} A promise that resolves to the transaction or null if not found.
+ */
+export async function txWithNonce(
+    connection: Connection,
+    noncePubkey: PublicKey,
+    instructions: TransactionInstruction[],
+    nonceInfo?: NonceAccount
+): Promise<Transaction | null> {
+    const tx = new Transaction()
+
+    if (!nonceInfo) {
+        const accountInfo = await connection.getAccountInfo(noncePubkey)
+        if (accountInfo) {
+            nonceInfo = NonceAccount.fromAccountData(accountInfo.data)
+        } else {
+            return null
+        }
+    }
+
+    tx.add(
+        // nonce advance must be the first insturction
+        SystemProgram.nonceAdvance({
+            noncePubkey: noncePubkey,
+            authorizedPubkey: nonceInfo.authorizedPubkey,
+        })
+    )
+    tx.add(...instructions)
+    tx.recentBlockhash = nonceInfo.nonce
+    return tx
+}
+
+/**
+ * Checks if an account is initialized.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} account - The account public key.
+ * @param {Commitment | GetAccountInfoConfig} [commitmentOrConfig] - The commitment level or account info configuration.
+ * @returns {Promise<boolean>} A promise that resolves to true if the account is initialized, false otherwise.
+ */
+export async function isAccountInitialized(
+    connection: Connection,
+    account: PublicKey,
+    commitmentOrConfig?: Commitment | GetAccountInfoConfig
+): Promise<boolean> {
+    return connection.getAccountInfo(account, commitmentOrConfig).then((res) => {
+        return res !== null
+    })
+}
+
+/**
+ * Builds a version 0 message.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} payerKey - The payer public key.
+ * @param {TransactionInstruction[]} instructions - The transaction instructions.
+ * @param {Commitment | GetAccountInfoConfig} [commitmentOrConfig='confirmed'] - The commitment level or account info configuration.
+ * @param {Blockhash} [blockhash] - The blockhash.
+ * @returns {Promise<MessageV0>} A promise that resolves to the version 0 message.
+ */
+export async function buildMessageV0(
+    connection: Connection,
+    payerKey: PublicKey,
+    instructions: TransactionInstruction[],
+    commitmentOrConfig: Commitment | GetAccountInfoConfig = 'confirmed',
+    blockhash?: Blockhash
+): Promise<MessageV0> {
+    return new TransactionMessage({
+        payerKey: payerKey,
+        recentBlockhash: blockhash ?? (await connection.getLatestBlockhash(commitmentOrConfig)).blockhash,
+        instructions: instructions,
+    }).compileToV0Message()
+}
+
+/**
+ * Builds a versioned transaction.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {PublicKey} payerKey - The payer public key.
+ * @param {TransactionInstruction[]} instructions - The transaction instructions.
+ * @param {Commitment | GetAccountInfoConfig} [commitmentOrConfig='confirmed'] - The commitment level or account info configuration.
+ * @param {Blockhash} [blockhash] - The blockhash.
+ * @param {PublicKey} [lookupTableAddress] - The lookup table address.
+ * @returns {Promise<VersionedTransaction>} A promise that resolves to the versioned transaction.
+ */
+export async function buildVersionedTransaction(
+    connection: Connection,
+    payerKey: PublicKey,
+    instructions: TransactionInstruction[],
+    commitmentOrConfig: Commitment | GetAccountInfoConfig = 'confirmed',
+    blockhash?: Blockhash,
+    lookupTableAddress?: PublicKey
+): Promise<VersionedTransaction> {
+    if (lookupTableAddress) {
+        return txWithAddressLookupTable(connection, payerKey, instructions, blockhash, lookupTableAddress)
+    }
+    return new VersionedTransaction(
+        await buildMessageV0(connection, payerKey, instructions, commitmentOrConfig, blockhash)
+    )
+}
+
+/**
+ * Generates an instruction discriminator.
+ *
+ * @param {string} method - The method name.
+ * @returns {Buffer} The instruction discriminator.
+ */
+export function instructionDiscriminator(method: string): Buffer {
+    return Buffer.from(sha2_256(Buffer.from(`global:${method}`))).subarray(0, 8)
+}
+
+/**
+ * Simulates a transaction.
+ *
+ * @param {Connection} connection - The connection to the Solana cluster.
+ * @param {TransactionInstruction[]} instructions - The transaction instructions.
+ * @param {PublicKey} programId - The program public key.
+ * @param {PublicKey} payer - The payer public key.
+ * @param {Commitment} [commitment='confirmed'] - The commitment level.
+ * @param {Blockhash} [blockhash] - The blockhash.
+ * @param {PublicKey} [lookupTableAddress] - The lookup table address.
+ * @returns {Promise<Buffer>} A promise that resolves to the simulation result.
+ * @throws {Error} If the simulation fails.
+ */
+export async function simulateTransaction(
+    connection: Connection,
+    instructions: TransactionInstruction[],
+    programId: PublicKey,
+    payer: PublicKey,
+    commitment: Commitment = 'confirmed',
+    blockhash?: Blockhash,
+    lookupTableAddress?: PublicKey
+): Promise<Buffer> {
+    const tx = await buildVersionedTransaction(
+        connection,
+        payer,
+        instructions,
+        commitment,
+        blockhash,
+        lookupTableAddress
+    )
+    const simulateResp = await connection.simulateTransaction(tx, { sigVerify: false, commitment })
+    const returnPrefix = `Program return: ${programId.toBase58()} `
+    const returnLog = simulateResp.value.logs?.find((l) => l.startsWith(returnPrefix))
+    if (returnLog === undefined || simulateResp.value.returnData?.programId !== programId.toBase58()) {
+        throw new Error(`Simulate Fail: ${JSON.stringify(simulateResp)}`)
+    } else {
+        return Buffer.from(returnLog.slice(returnPrefix.length), 'base64')
+    }
+}