solana-mint-recovery-engine 1.0.0

package/dist/src/commands/sign.d.ts

@@ -0,0 +1,4 @@
+export declare function runSign(envelopeFile: string, options: {
+    keypair: string;
+    output?: string;
+}): Promise<void>;

package/dist/src/commands/sign.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSign = runSign;
+const web3_js_1 = require("@solana/web3.js");
+const file_1 = require("../io/file");
+const signer_1 = require("../signers/signer");
+const chalk_1 = __importDefault(require("chalk"));
+const bs58_1 = __importDefault(require("bs58"));
+async function runSign(envelopeFile, options) {
+    try {
+        // 1. Load envelope
+        const envelope = (0, file_1.loadEnvelope)(envelopeFile);
+        // 2. Load keypair
+        const keypair = (0, signer_1.loadKeypair)(options.keypair);
+        const signerPubkey = keypair.publicKey;
+        // 3. Decode transaction
+        const tx = web3_js_1.Transaction.from(Buffer.from(envelope.rawTransactionB64, 'base64'));
+        // Check if this keypair is expected to sign
+        const isExpected = envelope.signatures.some(s => s.pubkey === signerPubkey.toBase58());
+        if (!isExpected) {
+            console.warn(chalk_1.default.yellow(`⚠ Warning: Keypair ${signerPubkey.toBase58()} is not in the list of expected signers for this transaction.`));
+        }
+        // 4. Sign transaction
+        console.log(`Signing transaction using key: ${signerPubkey.toBase58()}...`);
+        tx.partialSign(keypair);
+        // 5. Update raw transaction and signature metadata in envelope
+        const updatedSerialized = tx.serialize({
+            requireAllSignatures: false,
+            verifySignatures: false,
+        });
+        envelope.rawTransactionB64 = updatedSerialized.toString('base64');
+        // Update signature slots in envelope metadata
+        let signedCount = 0;
+        for (const sigSlot of envelope.signatures) {
+            const pubkeyObj = new web3_js_1.PublicKey(sigSlot.pubkey);
+            const signatureBuffer = tx.signatures.find(s => s.publicKey.equals(pubkeyObj))?.signature;
+            if (signatureBuffer) {
+                sigSlot.signature = bs58_1.default.encode(signatureBuffer);
+                signedCount++;
+            }
+        }
+        // 6. Write signed envelope back
+        const outputPath = options.output || envelopeFile;
+        (0, file_1.writeEnvelope)(outputPath, envelope);
+        console.log(chalk_1.default.green(`✔ Successfully signed transaction envelope! Saved to ${outputPath}`));
+        console.log(`Signatures: ${signedCount} of ${envelope.signatures.length} complete.`);
+    }
+    catch (err) {
+        console.error(chalk_1.default.red(`✘ Failed to sign transaction: ${err.message}`));
+        process.exit(1);
+    }
+}

package/dist/src/commands/simulate.d.ts

@@ -0,0 +1,3 @@
+export declare function runSimulate(envelopeFile: string, options: {
+    config?: string;
+}): Promise<void>;

package/dist/src/commands/simulate.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSimulate = runSimulate;
+const rpc_1 = require("../io/rpc");
+const file_1 = require("../io/file");
+const chalk_1 = __importDefault(require("chalk"));
+async function runSimulate(envelopeFile, options) {
+    try {
+        const config = (0, file_1.loadConfig)(options.config);
+        const rpc = new rpc_1.RpcAdapter(config.rpcUrl, config.commitment);
+        const envelope = (0, file_1.loadEnvelope)(envelopeFile);
+        console.log(`Loading transaction from ${envelopeFile}...`);
+        const rawTxBuf = Buffer.from(envelope.rawTransactionB64, 'base64');
+        console.log('Simulating transaction on-chain...');
+        const result = await rpc.simulateTransaction(rawTxBuf);
+        if (result.value.err) {
+            console.error(chalk_1.default.red('\n✘ Simulation FAILED!'));
+            console.error(chalk_1.default.red(`Error details: ${JSON.stringify(result.value.err)}`));
+            if (result.value.logs) {
+                console.log('\nSimulation Logs:');
+                result.value.logs.forEach((log) => console.log(chalk_1.default.gray(`  ${log}`)));
+            }
+            process.exit(5);
+        }
+        console.log(chalk_1.default.green('\n✔ Simulation SUCCESSFUL!'));
+        console.log(`Units Consumed: ${result.value.unitsConsumed || 'N/A'}`);
+        if (result.value.logs) {
+            console.log('\nSimulation Logs:');
+            result.value.logs.forEach((log) => {
+                if (log.includes('success') || log.includes('Success')) {
+                    console.log(chalk_1.default.green(`  ${log}`));
+                }
+                else if (log.includes('Instruction')) {
+                    console.log(chalk_1.default.cyan(`  ${log}`));
+                }
+                else {
+                    console.log(chalk_1.default.gray(`  ${log}`));
+                }
+            });
+        }
+        process.exit(0);
+    }
+    catch (err) {
+        console.error(chalk_1.default.red(`✘ Simulation error: ${err.message}`));
+        process.exit(1);
+    }
+}

package/dist/src/commands/submit.d.ts

@@ -0,0 +1,3 @@
+export declare function runSubmit(envelopeFile: string, options: {
+    config?: string;
+}): Promise<void>;

package/dist/src/commands/submit.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSubmit = runSubmit;
+const rpc_1 = require("../io/rpc");
+const file_1 = require("../io/file");
+const web3_js_1 = require("@solana/web3.js");
+const chalk_1 = __importDefault(require("chalk"));
+async function runSubmit(envelopeFile, options) {
+    try {
+        const config = (0, file_1.loadConfig)(options.config);
+        const rpc = new rpc_1.RpcAdapter(config.rpcUrl, config.commitment);
+        const envelope = (0, file_1.loadEnvelope)(envelopeFile);
+        // Decode transaction to read feePayer
+        const tx = web3_js_1.Transaction.from(Buffer.from(envelope.rawTransactionB64, 'base64'));
+        const feePayer = tx.feePayer;
+        if (!feePayer) {
+            throw new Error('Transaction has no fee payer specified.');
+        }
+        const threshold = envelope.metadata.multisigThreshold;
+        if (threshold !== undefined) {
+            // Multisig Account validation:
+            // Count how many co-signers have signed
+            const multisigSigners = envelope.signatures.filter(s => s.pubkey !== feePayer.toBase58());
+            const signedCoSigners = multisigSigners.filter(s => s.signature !== null).length;
+            if (signedCoSigners < threshold) {
+                throw new Error(`Multisig threshold of ${threshold} co-signers not met. Current co-signatures: ${signedCoSigners}/${multisigSigners.length}.`);
+            }
+            // Check fee payer signature
+            const feePayerSlot = envelope.signatures.find(s => s.pubkey === feePayer.toBase58());
+            if (feePayerSlot && feePayerSlot.signature === null) {
+                throw new Error(`Fee payer ${feePayer.toBase58()} signature is missing.`);
+            }
+        }
+        else {
+            // Standard Account validation: all signatures must be complete
+            const missingSignatures = envelope.signatures.filter(s => s.signature === null);
+            if (missingSignatures.length > 0) {
+                throw new Error(`Transaction envelope is missing signatures for: ${missingSignatures.map(s => s.pubkey).join(', ')}`);
+            }
+        }
+        console.log(`Loading signed transaction from ${envelopeFile}...`);
+        const rawTxBuf = Buffer.from(envelope.rawTransactionB64, 'base64');
+        console.log('Broadcasting transaction to Solana network...');
+        const signature = await rpc.submitTransaction(rawTxBuf);
+        console.log(chalk_1.default.green('\n✔ Transaction submitted successfully!'));
+        console.log(`Signature: ${signature}`);
+        console.log(chalk_1.default.cyan(`Explorer Link: https://explorer.solana.com/tx/${signature}?cluster=custom&customUrl=${encodeURIComponent(config.rpcUrl)}`));
+        process.exit(0);
+    }
+    catch (err) {
+        console.error(chalk_1.default.red(`✘ Submission failed: ${err.message}`));
+        process.exit(1);
+    }
+}

package/dist/src/core/rent.d.ts

@@ -0,0 +1,19 @@
+export interface RentParams {
+    lamportsPerByteYear: bigint;
+    exemptionMultiplier: bigint;
+}
+export declare const DEFAULT_RENT_PARAMS: RentParams;
+/**
+ * Calculates the exact rent-exempt floor and any excess lamports in an account.
+ *
+ * Formula:
+ * RentFloor = (dataSize + 128 bytes metadata) * lamportsPerByteYear * exemptionMultiplier
+ *
+ * @param dataSize The size of the account data in bytes
+ * @param balance The current balance of the account in lamports
+ * @param rentParams Parameters for rent calculation (defaults to Solana Mainnet)
+ */
+export declare function calculateExcessLamports(dataSize: number, balance: bigint, rentParams?: RentParams): {
+    excess: bigint;
+    rentFloor: bigint;
+};

package/dist/src/core/rent.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RENT_PARAMS = void 0;
+exports.calculateExcessLamports = calculateExcessLamports;
+exports.DEFAULT_RENT_PARAMS = {
+    lamportsPerByteYear: 3480n,
+    exemptionMultiplier: 2n,
+};
+/**
+ * Calculates the exact rent-exempt floor and any excess lamports in an account.
+ *
+ * Formula:
+ * RentFloor = (dataSize + 128 bytes metadata) * lamportsPerByteYear * exemptionMultiplier
+ *
+ * @param dataSize The size of the account data in bytes
+ * @param balance The current balance of the account in lamports
+ * @param rentParams Parameters for rent calculation (defaults to Solana Mainnet)
+ */
+function calculateExcessLamports(dataSize, balance, rentParams = exports.DEFAULT_RENT_PARAMS) {
+    const baseSize = BigInt(dataSize) + 128n;
+    const rentFloor = baseSize * rentParams.lamportsPerByteYear * rentParams.exemptionMultiplier;
+    if (balance <= rentFloor) {
+        return { excess: 0n, rentFloor };
+    }
+    return { excess: balance - rentFloor, rentFloor };
+}

package/dist/src/core/transaction.d.ts

@@ -0,0 +1,22 @@
+import { PublicKey, TransactionInstruction } from '@solana/web3.js';
+export declare const TOKEN_2022_PROGRAM_ID: PublicKey;
+/**
+ * Manually constructs the WithdrawExcessLamports instruction for Token-2022.
+ * Discriminator: 38
+ */
+export declare function createWithdrawExcessLamportsInstruction(source: PublicKey, destination: PublicKey, authority: PublicKey, multiSigners?: PublicKey[]): TransactionInstruction;
+export interface RecoveryTxParams {
+    source: PublicKey;
+    destination: PublicKey;
+    authority: PublicKey;
+    excessAmount: bigint;
+    developerFeeWallet?: PublicKey;
+    feePercentage?: number;
+    multiSigners?: PublicKey[];
+}
+/**
+ * Builds the transaction instructions for recovering excess lamports.
+ * Uses the Token-2022 WithdrawExcessLamports instruction.
+ * Optionally appends a SystemProgram transfer for fee splitting.
+ */
+export declare function buildRecoveryInstructions(params: RecoveryTxParams): TransactionInstruction[];

package/dist/src/core/transaction.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOKEN_2022_PROGRAM_ID = void 0;
+exports.createWithdrawExcessLamportsInstruction = createWithdrawExcessLamportsInstruction;
+exports.buildRecoveryInstructions = buildRecoveryInstructions;
+const web3_js_1 = require("@solana/web3.js");
+exports.TOKEN_2022_PROGRAM_ID = new web3_js_1.PublicKey('TokenzQdBNbLqP55ePE1R24g5652uhGzTsw34JmUCwm');
+/**
+ * Manually constructs the WithdrawExcessLamports instruction for Token-2022.
+ * Discriminator: 38
+ */
+function createWithdrawExcessLamportsInstruction(source, destination, authority, multiSigners = []) {
+    const keys = [
+        { pubkey: source, isSigner: false, isWritable: true },
+        { pubkey: destination, isSigner: false, isWritable: true },
+        { pubkey: authority, isSigner: multiSigners.length === 0, isWritable: false },
+    ];
+    for (const signer of multiSigners) {
+        keys.push({ pubkey: signer, isSigner: true, isWritable: false });
+    }
+    // Discriminator is 38
+    const data = Buffer.alloc(1);
+    data.writeUInt8(38, 0);
+    return new web3_js_1.TransactionInstruction({
+        keys,
+        programId: exports.TOKEN_2022_PROGRAM_ID,
+        data,
+    });
+}
+/**
+ * Builds the transaction instructions for recovering excess lamports.
+ * Uses the Token-2022 WithdrawExcessLamports instruction.
+ * Optionally appends a SystemProgram transfer for fee splitting.
+ */
+function buildRecoveryInstructions(params) {
+    const { source, destination, authority, excessAmount, developerFeeWallet, feePercentage = 10, multiSigners = [], } = params;
+    const instructions = [];
+    // 1. Create the WithdrawExcessLamports instruction
+    const withdrawInstruction = createWithdrawExcessLamportsInstruction(source, destination, authority, multiSigners);
+    instructions.push(withdrawInstruction);
+    // 2. If developer fee is requested, calculate and add the transfer instruction
+    if (developerFeeWallet && feePercentage > 0) {
+        const feeAmount = (excessAmount * BigInt(feePercentage)) / 100n;
+        if (feeAmount > 0n) {
+            const feeTransferInstruction = web3_js_1.SystemProgram.transfer({
+                fromPubkey: destination,
+                toPubkey: developerFeeWallet,
+                lamports: Number(feeAmount),
+            });
+            instructions.push(feeTransferInstruction);
+        }
+    }
+    return instructions;
+}

package/dist/src/core/validation.d.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+export declare const ConfigSchema: z.ZodObject<{
+    rpcUrl: z.ZodDefault<z.ZodString>;
+    commitment: z.ZodDefault<z.ZodEnum<["processed", "confirmed", "finalized"]>>;
+    defaultDestination: z.ZodOptional<z.ZodString>;
+    feeWallet: z.ZodOptional<z.ZodString>;
+    feePercentage: z.ZodDefault<z.ZodNumber>;
+    rentOverride: z.ZodOptional<z.ZodObject<{
+        lamportsPerByteYear: z.ZodString;
+        exemptionMultiplier: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        lamportsPerByteYear: string;
+        exemptionMultiplier: string;
+    }, {
+        lamportsPerByteYear: string;
+        exemptionMultiplier: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    feePercentage: number;
+    rpcUrl: string;
+    commitment: "processed" | "confirmed" | "finalized";
+    defaultDestination?: string | undefined;
+    feeWallet?: string | undefined;
+    rentOverride?: {
+        lamportsPerByteYear: string;
+        exemptionMultiplier: string;
+    } | undefined;
+}, {
+    feePercentage?: number | undefined;
+    rpcUrl?: string | undefined;
+    commitment?: "processed" | "confirmed" | "finalized" | undefined;
+    defaultDestination?: string | undefined;
+    feeWallet?: string | undefined;
+    rentOverride?: {
+        lamportsPerByteYear: string;
+        exemptionMultiplier: string;
+    } | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare const TxEnvelopeSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodString>;
+    type: z.ZodLiteral<"withdraw-excess-lamports">;
+    metadata: z.ZodObject<{
+        sourceAddress: z.ZodString;
+        sourceType: z.ZodEnum<["token-account", "mint", "multisig"]>;
+        destinationAddress: z.ZodString;
+        authorityAddress: z.ZodString;
+        excessLamports: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        rentFloor: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        createdAt: z.ZodString;
+        blockhash: z.ZodString;
+        multisigThreshold: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        blockhash: string;
+        sourceAddress: string;
+        sourceType: "token-account" | "mint" | "multisig";
+        destinationAddress: string;
+        authorityAddress: string;
+        excessLamports: string | number;
+        rentFloor: string | number;
+        createdAt: string;
+        multisigThreshold?: number | undefined;
+    }, {
+        blockhash: string;
+        sourceAddress: string;
+        sourceType: "token-account" | "mint" | "multisig";
+        destinationAddress: string;
+        authorityAddress: string;
+        excessLamports: string | number;
+        rentFloor: string | number;
+        createdAt: string;
+        multisigThreshold?: number | undefined;
+    }>;
+    rawTransactionB64: z.ZodString;
+    signatures: z.ZodArray<z.ZodObject<{
+        pubkey: z.ZodString;
+        signature: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        signature: string | null;
+        pubkey: string;
+    }, {
+        signature: string | null;
+        pubkey: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    signatures: {
+        signature: string | null;
+        pubkey: string;
+    }[];
+    version: string;
+    type: "withdraw-excess-lamports";
+    metadata: {
+        blockhash: string;
+        sourceAddress: string;
+        sourceType: "token-account" | "mint" | "multisig";
+        destinationAddress: string;
+        authorityAddress: string;
+        excessLamports: string | number;
+        rentFloor: string | number;
+        createdAt: string;
+        multisigThreshold?: number | undefined;
+    };
+    rawTransactionB64: string;
+}, {
+    signatures: {
+        signature: string | null;
+        pubkey: string;
+    }[];
+    type: "withdraw-excess-lamports";
+    metadata: {
+        blockhash: string;
+        sourceAddress: string;
+        sourceType: "token-account" | "mint" | "multisig";
+        destinationAddress: string;
+        authorityAddress: string;
+        excessLamports: string | number;
+        rentFloor: string | number;
+        createdAt: string;
+        multisigThreshold?: number | undefined;
+    };
+    rawTransactionB64: string;
+    version?: string | undefined;
+}>;
+export type TxEnvelope = z.infer<typeof TxEnvelopeSchema>;

package/dist/src/core/validation.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TxEnvelopeSchema = exports.ConfigSchema = void 0;
+const zod_1 = require("zod");
+exports.ConfigSchema = zod_1.z.object({
+    rpcUrl: zod_1.z.string().url().default('https://api.mainnet-beta.solana.com'),
+    commitment: zod_1.z.enum(['processed', 'confirmed', 'finalized']).default('confirmed'),
+    defaultDestination: zod_1.z.string().optional(),
+    feeWallet: zod_1.z.string().optional(),
+    feePercentage: zod_1.z.number().min(0).max(100).default(10),
+    rentOverride: zod_1.z.object({
+        lamportsPerByteYear: zod_1.z.string(),
+        exemptionMultiplier: zod_1.z.string(),
+    }).optional(),
+});
+exports.TxEnvelopeSchema = zod_1.z.object({
+    version: zod_1.z.string().default('1.0.0'),
+    type: zod_1.z.literal('withdraw-excess-lamports'),
+    metadata: zod_1.z.object({
+        sourceAddress: zod_1.z.string(),
+        sourceType: zod_1.z.enum(['token-account', 'mint', 'multisig']),
+        destinationAddress: zod_1.z.string(),
+        authorityAddress: zod_1.z.string(),
+        excessLamports: zod_1.z.union([zod_1.z.number(), zod_1.z.string()]),
+        rentFloor: zod_1.z.union([zod_1.z.number(), zod_1.z.string()]),
+        createdAt: zod_1.z.string(),
+        blockhash: zod_1.z.string(),
+        multisigThreshold: zod_1.z.number().optional(),
+    }),
+    rawTransactionB64: zod_1.z.string(),
+    signatures: zod_1.z.array(zod_1.z.object({
+        pubkey: zod_1.z.string(),
+        signature: zod_1.z.string().nullable(),
+    })),
+});

package/dist/src/io/file.d.ts

@@ -0,0 +1,23 @@
+import { PublicKey } from '@solana/web3.js';
+import { Config, TxEnvelope } from '../core/validation';
+/**
+ * Loads and parses the configuration file. Falls back to default config if missing.
+ */
+export declare function loadConfig(configPath?: string): Config;
+/**
+ * Writes the configuration file to the specified path.
+ */
+export declare function writeConfig(configPath: string, config: Config): void;
+/**
+ * Reads a list of target public keys from a file.
+ * Supports comma, space, or newline-separated addresses.
+ */
+export declare function loadAddresses(filePath: string): PublicKey[];
+/**
+ * Loads a transaction envelope from a file and validates it.
+ */
+export declare function loadEnvelope(filePath: string): TxEnvelope;
+/**
+ * Writes a transaction envelope to a file.
+ */
+export declare function writeEnvelope(filePath: string, envelope: TxEnvelope): void;

package/dist/src/io/file.js

@@ -0,0 +1,140 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.writeConfig = writeConfig;
+exports.loadAddresses = loadAddresses;
+exports.loadEnvelope = loadEnvelope;
+exports.writeEnvelope = writeEnvelope;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const web3_js_1 = require("@solana/web3.js");
+const validation_1 = require("../core/validation");
+const signer_1 = require("../signers/signer");
+/**
+ * Loads and parses the configuration file. Falls back to default config if missing.
+ */
+function loadConfig(configPath) {
+    const defaultPath = path.join(process.cwd(), 'smre.config.json');
+    const targetPath = configPath ? (0, signer_1.resolveHome)(configPath) : defaultPath;
+    if (!fs.existsSync(targetPath)) {
+        // Return default Zod values
+        return validation_1.ConfigSchema.parse({});
+    }
+    try {
+        const raw = fs.readFileSync(targetPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return validation_1.ConfigSchema.parse(parsed);
+    }
+    catch (err) {
+        throw new Error(`Invalid configuration file at ${targetPath}: ${err.message}`);
+    }
+}
+/**
+ * Writes the configuration file to the specified path.
+ */
+function writeConfig(configPath, config) {
+    const resolved = (0, signer_1.resolveHome)(configPath);
+    try {
+        const dir = path.dirname(resolved);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(resolved, JSON.stringify(config, null, 2), 'utf8');
+    }
+    catch (err) {
+        throw new Error(`Failed to write config to ${resolved}: ${err.message}`);
+    }
+}
+/**
+ * Reads a list of target public keys from a file.
+ * Supports comma, space, or newline-separated addresses.
+ */
+function loadAddresses(filePath) {
+    const resolved = (0, signer_1.resolveHome)(filePath);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Target address file not found at: ${filePath}`);
+    }
+    try {
+        const raw = fs.readFileSync(resolved, 'utf8');
+        const lines = raw.split(/[\r\n, \t]+/).map(line => line.trim()).filter(line => line.length > 0);
+        const keys = [];
+        for (const line of lines) {
+            try {
+                keys.push(new web3_js_1.PublicKey(line));
+            }
+            catch (err) {
+                throw new Error(`Invalid public key "${line}" found in address list.`);
+            }
+        }
+        return keys;
+    }
+    catch (err) {
+        throw new Error(`Failed to parse target addresses: ${err.message}`);
+    }
+}
+/**
+ * Loads a transaction envelope from a file and validates it.
+ */
+function loadEnvelope(filePath) {
+    const resolved = (0, signer_1.resolveHome)(filePath);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Transaction envelope file not found at: ${filePath}`);
+    }
+    try {
+        const raw = fs.readFileSync(resolved, 'utf8');
+        const parsed = JSON.parse(raw);
+        return validation_1.TxEnvelopeSchema.parse(parsed);
+    }
+    catch (err) {
+        throw new Error(`Invalid transaction envelope at ${filePath}: ${err.message}`);
+    }
+}
+/**
+ * Writes a transaction envelope to a file.
+ */
+function writeEnvelope(filePath, envelope) {
+    const resolved = (0, signer_1.resolveHome)(filePath);
+    try {
+        const dir = path.dirname(resolved);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(resolved, JSON.stringify(envelope, null, 2), 'utf8');
+    }
+    catch (err) {
+        throw new Error(`Failed to write transaction envelope to ${resolved}: ${err.message}`);
+    }
+}

package/dist/src/io/rpc.d.ts

@@ -0,0 +1,36 @@
+import { PublicKey, Commitment } from '@solana/web3.js';
+export type AccountType = 'token-account' | 'mint' | 'multisig';
+export interface InspectedAccount {
+    address: PublicKey;
+    type: AccountType;
+    ownerProgram: PublicKey;
+    balance: bigint;
+    dataSize: number;
+    authority: PublicKey | null;
+    multisigSigners?: PublicKey[];
+    multisigThreshold?: number;
+    isToken2022: boolean;
+}
+/**
+ * Adapter class to query Solana RPC node.
+ */
+export declare class RpcAdapter {
+    private connection;
+    constructor(rpcUrl: string, commitment?: Commitment);
+    /**
+     * Fetches the latest blockhash from the RPC.
+     */
+    getLatestBlockhash(): Promise<string>;
+    /**
+     * Submits a serialized transaction to the network.
+     */
+    submitTransaction(rawTransactionBuf: Buffer): Promise<string>;
+    /**
+     * Simulates a transaction.
+     */
+    simulateTransaction(rawTransactionBuf: Buffer): Promise<any>;
+    /**
+     * Inspects a Solana token or mint account.
+     */
+    inspectAccount(address: PublicKey): Promise<InspectedAccount>;
+}