@layerzerolabs/test-utils-stellar 0.2.122

package/src/deploy.ts

@@ -0,0 +1,316 @@
+import type { Keypair } from '@stellar/stellar-sdk';
+import {
+    Asset,
+    BASE_FEE,
+    hash,
+    Operation,
+    rpc,
+    TransactionBuilder,
+    xdr,
+} from '@stellar/stellar-sdk';
+import { readFileSync } from 'fs';
+
+import type { StellarTestEnv } from './env.js';
+
+export interface DeployableContractClient<T extends { options: { contractId: string } }> {
+    deploy: (
+        argsOrOptions: unknown,
+        options?: unknown,
+    ) => Promise<{ signAndSend: () => Promise<{ result: T }> }>;
+}
+
+/**
+ * Query and display the TTL (Time To Live) of uploaded WASM code.
+ *
+ * @param env - Stellar test environment (RPC URL, etc.)
+ * @param wasmHash - The hex-encoded SHA-256 hash of the WASM code
+ * @param server - The Stellar RPC server instance
+ */
+async function queryWasmTtl(
+    env: StellarTestEnv,
+    wasmHash: string,
+    server: rpc.Server,
+): Promise<void> {
+    try {
+        const latestLedger = await server.getLatestLedger();
+        const currentLedger = latestLedger.sequence;
+
+        // Create the LedgerKey for contract code using XDR encoding
+        const wasmHashBuffer = Buffer.from(wasmHash, 'hex');
+        // Ensure hash is exactly 32 bytes
+        const hashBytes =
+            wasmHashBuffer.length === 32 ? wasmHashBuffer : wasmHashBuffer.slice(0, 32);
+        // Create LedgerKeyContractCode with hash
+        const ledgerKeyContractCode = new xdr.LedgerKeyContractCode({
+            hash: hashBytes,
+        });
+        const ledgerKey = xdr.LedgerKey.contractCode(ledgerKeyContractCode);
+        const ledgerKeyXdr = ledgerKey.toXDR('base64');
+
+        // Query contract code entry using direct RPC call
+        const response = await fetch(env.RPC_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'getLedgerEntries',
+                params: {
+                    keys: [ledgerKeyXdr],
+                },
+            }),
+        });
+
+        const result = (await response.json()) as any;
+        if (result.error) {
+            console.warn(`Warning: Could not retrieve WASM TTL: ${result.error.message}`);
+        } else if (result.result?.entries?.[0]?.liveUntilLedgerSeq) {
+            const liveUntilLedgerSeq = result.result.entries[0].liveUntilLedgerSeq;
+            const ttlLedgers = liveUntilLedgerSeq - currentLedger;
+            const ttlDays = (ttlLedgers * 5) / (24 * 3600); // ~5 seconds per ledger
+            console.log(
+                `⏰ WASM TTL: live until ledger ${liveUntilLedgerSeq} (${ttlLedgers} ledgers remaining, ~${ttlDays.toFixed(2)} days)`,
+            );
+        }
+    } catch (error) {
+        // If querying TTL fails, it might be because the code isn't indexed yet
+        // This is non-fatal, so we just log a warning
+        console.warn(
+            `Warning: Could not retrieve WASM TTL: ${error instanceof Error ? error.message : String(error)}`,
+        );
+    }
+}
+
+export async function uploadWasm(
+    env: StellarTestEnv,
+    wasmBuffer: Buffer,
+    keypair: Keypair,
+    server: rpc.Server,
+): Promise<string> {
+    console.log(
+        `📦 WASM buffer size: ${wasmBuffer.length} bytes (${(wasmBuffer.length / 1024).toFixed(2)} KB)`,
+    );
+
+    const account = await server.getAccount(keypair.publicKey());
+
+    const uploadTx = new TransactionBuilder(account, {
+        fee: BASE_FEE,
+        networkPassphrase: env.NETWORK_PASSPHRASE,
+    })
+        .addOperation(Operation.uploadContractWasm({ wasm: wasmBuffer }))
+        .setTimeout(30)
+        .build();
+
+    const simulated = await server.simulateTransaction(uploadTx);
+    const preparedTx = rpc.assembleTransaction(uploadTx, simulated).build();
+
+    console.log(
+        `💰 Upload transaction fee: ${preparedTx.fee} stroops (${(Number(preparedTx.fee) / 10000000).toFixed(7)} XLM)`,
+    );
+
+    preparedTx.sign(keypair);
+
+    const sendResult = await server.sendTransaction(preparedTx);
+
+    if (sendResult.status !== 'PENDING') {
+        throw new Error(`Transaction failed: ${JSON.stringify(sendResult)}`);
+    }
+
+    // Wait for transaction to be confirmed
+    const txResult = await server.pollTransaction(sendResult.hash);
+
+    if (txResult.status !== 'SUCCESS') {
+        throw new Error(`Transaction not successful: ${JSON.stringify(txResult)}`);
+    }
+
+    // Compute the WASM hash (SHA-256 of the WASM bytes)
+    const wasmHash = hash(wasmBuffer).toString('hex');
+
+    // Query and display the WASM code TTL
+    await queryWasmTtl(env, wasmHash, server);
+
+    return wasmHash;
+}
+
+/**
+ * Generic contract deployment helper that works with any contract Client
+ *
+ * @param ClientClass - The contract Client class (e.g., EndpointClient, SMLClient)
+ * @param wasmFilePath - Path to the compiled WASM file
+ * @param constructorArgs - Arguments for the contract's constructor
+ * @param deployer - The keypair that will deploy the contract
+ * @param options - Optional deployment options (salt, fee, timeout, etc.)
+ * @returns The deployed contract's Client instance with the contractId
+ */
+export async function deployContract<T extends { options: { contractId: string } }>(
+    env: StellarTestEnv,
+    ClientClass: DeployableContractClient<T>,
+    wasmFilePath: string,
+    constructorArgs: unknown,
+    deployer: Keypair,
+    options: {
+        salt?: Buffer;
+        wasmHash?: string;
+        rpcUrl?: string;
+        networkPassphrase?: string;
+        allowHttp?: boolean;
+    } = {},
+): Promise<T> {
+    const {
+        rpcUrl = env.RPC_URL,
+        networkPassphrase = env.NETWORK_PASSPHRASE,
+        allowHttp = true,
+        salt,
+    } = options;
+
+    const server = new rpc.Server(rpcUrl, {
+        allowHttp: allowHttp,
+    });
+
+    let wasmHash = options.wasmHash;
+    if (wasmHash) {
+        console.log('📦 Using pre-uploaded WASM hash:', wasmHash);
+    } else {
+        // Step 1: Read WASM file
+        console.log('📖 Reading WASM file from:', wasmFilePath);
+        const wasmBuffer = readFileSync(wasmFilePath);
+
+        // Step 2: Upload WASM and get hash
+        console.log('📤 Uploading WASM...');
+        wasmHash = await uploadWasm(env, wasmBuffer, deployer, server);
+        console.log('✅ WASM uploaded, hash:', wasmHash);
+    }
+
+    // Step 3: Deploy the contract
+    console.log('🚀 Deploying contract...');
+    const deployOptions = {
+        wasmHash,
+        publicKey: deployer.publicKey(),
+        signTransaction: async (tx: string) => {
+            const transaction = TransactionBuilder.fromXDR(tx, networkPassphrase);
+            transaction.sign(deployer);
+            return {
+                signedTxXdr: transaction.toXDR(),
+                signerAddress: deployer.publicKey(),
+            };
+        },
+        rpcUrl,
+        networkPassphrase,
+        allowHttp,
+        salt,
+    };
+    const deployTx =
+        constructorArgs == null
+            ? await ClientClass.deploy(deployOptions)
+            : await ClientClass.deploy(constructorArgs, deployOptions);
+
+    // Step 4: Sign and send
+    const sentTx = await deployTx.signAndSend();
+
+    // Step 5: Extract contract ID from result
+    const contractClient = sentTx.result;
+    const contractId = contractClient.options.contractId;
+    console.log('✅ Contract deployed at:', contractId);
+
+    return contractClient;
+}
+
+export async function deployNativeSac(env: StellarTestEnv): Promise<void> {
+    await deployAssetSac(env, Asset.native());
+    console.log('✅ Native SAC deployed');
+}
+
+export async function deployZroToken(env: StellarTestEnv): Promise<void> {
+    const server = new rpc.Server(env.RPC_URL, {
+        allowHttp: true,
+    });
+
+    // First, issue the ZRO token.
+    // We can't changeTrust of Issuer account, because the Issuer can't hold the asset.
+    const account = await server.getAccount(env.DEFAULT_DEPLOYER.publicKey());
+    const transaction = new TransactionBuilder(account, {
+        fee: BASE_FEE,
+        networkPassphrase: env.NETWORK_PASSPHRASE,
+    })
+        .addOperation(
+            Operation.changeTrust({
+                asset: env.ZRO_ASSET,
+                source: env.ZRO_DISTRIBUTOR.publicKey(),
+            }),
+        )
+        .addOperation(
+            Operation.payment({
+                asset: env.ZRO_ASSET,
+                amount: '10000',
+                destination: env.ZRO_DISTRIBUTOR.publicKey(),
+            }),
+        )
+        .setTimeout(10)
+        .build();
+    transaction.sign(env.DEFAULT_DEPLOYER, env.ZRO_DISTRIBUTOR);
+
+    const sendResult = await server.sendTransaction(transaction);
+    if (sendResult.status !== 'PENDING') {
+        throw new Error(`Failed to issue ZRO token: ${JSON.stringify(sendResult)}`);
+    }
+    const txResult = await server.pollTransaction(sendResult.hash);
+    if (txResult.status !== 'SUCCESS') {
+        throw new Error(`Failed to issue ZRO token: ${JSON.stringify(txResult)}`);
+    }
+    console.log('✅ ZRO asset issued');
+
+    // Deploy the Stellar Asset Contract (SAC)
+    await deployAssetSac(env, env.ZRO_ASSET);
+    console.log('✅ ZRO SAC deployed');
+}
+
+/**
+ * Deploy SAC for a custom asset using TypeScript
+ */
+export async function deployAssetSac(env: StellarTestEnv, asset: Asset): Promise<string> {
+    console.log('Deploying SAC for asset:', asset.toString());
+
+    const server = new rpc.Server(env.RPC_URL, { allowHttp: true });
+    const account = await server.getAccount(env.DEFAULT_DEPLOYER.publicKey());
+
+    // Build transaction with createStellarAssetContract operation
+    const deployTx = new TransactionBuilder(account, {
+        fee: BASE_FEE,
+        networkPassphrase: env.NETWORK_PASSPHRASE,
+    })
+        .addOperation(
+            Operation.createStellarAssetContract({
+                asset: asset,
+            }),
+        )
+        .setTimeout(30)
+        .build();
+
+    // Simulate transaction first (required for contract operations)
+    const simulated = await server.simulateTransaction(deployTx);
+
+    // Check if simulation was successful
+    if (rpc.Api.isSimulationError(simulated)) {
+        // Soroban returns ExistingValue when the contract is already deployed.
+        // This is expected on container reuse (local dev reruns).
+        if (simulated.error?.includes('ExistingValue')) {
+            console.log(`SAC for ${asset.toString()} already deployed, skipping`);
+            return asset.contractId(env.NETWORK_PASSPHRASE);
+        }
+        throw new Error(`Transaction simulation failed: ${JSON.stringify(simulated)}`);
+    }
+
+    const preparedTx = rpc.assembleTransaction(deployTx, simulated).build();
+
+    // Sign and send
+    preparedTx.sign(env.DEFAULT_DEPLOYER);
+    const sendResult = await server.sendTransaction(preparedTx);
+    if (sendResult.status !== 'PENDING') {
+        throw new Error(`Failed to deploy SAC: ${JSON.stringify(sendResult)}`);
+    }
+    const txResult = await server.pollTransaction(sendResult.hash);
+    if (txResult.status !== 'SUCCESS') {
+        throw new Error(`SAC deployment not successful: ${JSON.stringify(txResult)}`);
+    }
+    return asset.contractId(env.NETWORK_PASSPHRASE);
+}

package/src/env.ts

@@ -0,0 +1,104 @@
+import { Asset, Keypair, Networks } from '@stellar/stellar-sdk';
+
+import { Secp256k1KeyPair } from './secp256k1.js';
+
+export interface CreateStellarTestEnvOptions {
+    /** Docker container name — must be unique when suites run concurrently. */
+    containerName: string;
+    /** Host port mapped to the localnet container's RPC port. */
+    hostPort: number;
+    /**
+     * Optional localnet image override. Defaults to the versioned LayerZero ECR snapshot.
+     * Useful for testing a locally built image without changing the shared default.
+     */
+    dockerImage?: string;
+}
+
+/**
+ * Shared Stellar E2E constants (RPC URL, keys, EIDs, token addresses).
+ * Constructed from containerName/hostPort so concurrent suites do not collide.
+ */
+export interface StellarTestEnv {
+    CONTAINER_NAME: string;
+    HOST_PORT: number;
+    /** Optional localnet Docker image override. */
+    DOCKER_IMAGE?: string;
+    RPC_URL: string;
+    NETWORK_PASSPHRASE: typeof Networks.STANDALONE;
+    JUNK_WALLET: Keypair;
+    DEFAULT_DEPLOYER: Keypair;
+    ZRO_DISTRIBUTOR: Keypair;
+    EXECUTOR_ADMIN: Keypair;
+    CHAIN_B_DEPLOYER: Keypair;
+    DVN_SIGNER: Secp256k1KeyPair;
+    DVN_VID: number;
+    EID_A: number;
+    EID_B: number;
+    /** Legacy single EID (alias of EID_A). */
+    EID: number;
+    NATIVE_TOKEN_ADDRESS: string;
+    ZRO_ASSET: Asset;
+    ZRO_TOKEN_ADDRESS: string;
+    MSG_TYPE_VANILLA: number;
+    MSG_TYPE_COMPOSED: number;
+    MSG_TYPE_ABA: number;
+    MSG_TYPE_COMPOSED_ABA: number;
+}
+
+export function createStellarTestEnv(options: CreateStellarTestEnvOptions): StellarTestEnv {
+    const { containerName, hostPort, dockerImage } = options;
+    const networkPassphrase = Networks.STANDALONE;
+    const coreUrl = `http://localhost:${hostPort}`;
+
+    // Pre-funded in the ECR localnet image (BIP39: "test test...junk", path m/44'/148'/0')
+    const junkWallet = Keypair.fromSecret(
+        'SCZ5VBFVGE4SLZV5WJO33LEEU36EEOEHWO27KYJIIUWGOKZB2OSNAQBI',
+    );
+    const defaultDeployer = Keypair.fromSecret(
+        'SDLCA3JUES3G6R4FTI6XXDIWW7QCNMZNWPYQQIKQ26TEIZUFOLIVIUDK',
+    );
+    const zroDistributor = Keypair.fromSecret(
+        'SB6QAFXFRR2MXYHW4RRZ23JDGKHDCYCT5YTQEGG3WNT5VKZADJQFVNWG',
+    );
+    // Deterministic so globalSetup and test files agree (separate processes).
+    const executorAdmin = Keypair.fromSecret(
+        'SACWJCNRT2AYRPBWW7IBRNI765EMZSWPXXAAHYN57UFQNOXMGET7HM5K',
+    );
+    // Separate deployer for Chain B parallel deploy in protocol globalSetup.
+    const chainBDeployer = Keypair.fromSecret(
+        'SDLIZSTG7W4C3FZYY52WIKF7FTWAXCWC5Z4OVVF3TDA3MBOR37LMIANJ',
+    );
+
+    // Private key is keccak256("dvn_test_signer") truncated to 32 bytes
+    const dvnSigner = new Secp256k1KeyPair(
+        '0x8d3f8d5d8f1c7e2a5b4c3d6e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a',
+    );
+
+    const eidA = 30401;
+    const zroAsset = new Asset('ZRO', defaultDeployer.publicKey());
+
+    return {
+        CONTAINER_NAME: containerName,
+        HOST_PORT: hostPort,
+        DOCKER_IMAGE: dockerImage,
+        RPC_URL: `${coreUrl}/soroban/rpc`,
+        NETWORK_PASSPHRASE: networkPassphrase,
+        JUNK_WALLET: junkWallet,
+        DEFAULT_DEPLOYER: defaultDeployer,
+        ZRO_DISTRIBUTOR: zroDistributor,
+        EXECUTOR_ADMIN: executorAdmin,
+        CHAIN_B_DEPLOYER: chainBDeployer,
+        DVN_SIGNER: dvnSigner,
+        DVN_VID: 1,
+        EID_A: eidA,
+        EID_B: 30402,
+        EID: eidA,
+        NATIVE_TOKEN_ADDRESS: Asset.native().contractId(networkPassphrase),
+        ZRO_ASSET: zroAsset,
+        ZRO_TOKEN_ADDRESS: zroAsset.contractId(networkPassphrase),
+        MSG_TYPE_VANILLA: 1,
+        MSG_TYPE_COMPOSED: 2,
+        MSG_TYPE_ABA: 3,
+        MSG_TYPE_COMPOSED_ABA: 4,
+    };
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+export { createClient } from './client.js';
+export {
+    deployAssetSac,
+    deployContract,
+    deployNativeSac,
+    deployZroToken,
+    uploadWasm,
+} from './deploy.js';
+export {
+    createStellarTestEnv,
+    type CreateStellarTestEnvOptions,
+    type StellarTestEnv,
+} from './env.js';
+export { fundAccount, startStellarLocalnet, stopStellarLocalnet } from './localnet.js';
+export { createLocalnetOnlyGlobalSetup } from './localnet-global-setup.js';
+export {
+    type ChainAddresses,
+    createProtocolStackGlobalSetup,
+    type ProtocolContractModule,
+    type ProtocolGlobalSetupContext,
+    type ProtocolStackGlobalSetupOptions,
+    type ProtocolStackModules,
+} from './protocol-global-setup.js';
+export {
+    type EventFilter,
+    type PacketSentEvent,
+    type ParsedContractEvent,
+    scanEvents,
+    scanPacketSentEvents,
+    waitAndScanEvents,
+} from './scan.js';
+export { Secp256k1KeyPair } from './secp256k1.js';
+export {
+    assertTransactionSucceeded,
+    getNativeBalance,
+    getTokenAuthorized,
+    getTokenBalance,
+    signAndSendWithExecutorAuth,
+    signDvnAuthEntries,
+} from './utils.js';

package/src/localnet-global-setup.ts

@@ -0,0 +1,30 @@
+import type { StellarTestEnv } from './env.js';
+import { startStellarLocalnet, stopStellarLocalnet } from './localnet.js';
+
+/**
+ * Vitest globalSetup that only starts/stops Stellar localnet.
+ * Use when the suite deploys its own contracts (e.g. protocol SDK upgrader tests).
+ */
+export function createLocalnetOnlyGlobalSetup(
+    env: StellarTestEnv,
+): (_ctx?: unknown) => Promise<() => Promise<void>> {
+    return async function globalSetup(_ctx?: unknown): Promise<() => Promise<void>> {
+        console.log('\n========================================');
+        console.log('🌐 GLOBAL SETUP: Starting Stellar Localnet');
+        console.log('========================================\n');
+
+        await startStellarLocalnet({ env });
+
+        console.log('\n========================================');
+        console.log('✅ GLOBAL SETUP COMPLETE (localnet only)');
+        console.log('========================================\n');
+
+        return async () => {
+            console.log('\n========================================');
+            console.log('🛑 GLOBAL TEARDOWN: Stopping Stellar Localnet');
+            console.log('========================================\n');
+
+            await stopStellarLocalnet({ env });
+        };
+    };
+}