@prktsol/prkt 1.0.0

package/dist/cli/utils/output.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printResult = printResult;
+exports.txExplorer = txExplorer;
+exports.addressExplorer = addressExplorer;
+exports.failWithMessage = failWithMessage;
+const chalk_1 = __importDefault(require("chalk"));
+function printResult(output, payload, title) {
+    if (output.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    if (title) {
+        console.log(chalk_1.default.cyan(title));
+    }
+    if (Array.isArray(payload)) {
+        if (payload.length === 0) {
+            console.log(chalk_1.default.yellow("No records."));
+            return;
+        }
+        console.table(payload);
+        return;
+    }
+    if (typeof payload === "object" && payload !== null) {
+        console.table([payload]);
+        return;
+    }
+    console.log(payload);
+}
+function txExplorer(signature) {
+    return `https://explorer.solana.com/tx/${signature}?cluster=devnet`;
+}
+function addressExplorer(address) {
+    return `https://explorer.solana.com/address/${address}?cluster=devnet`;
+}
+function failWithMessage(error) {
+    if (error instanceof Error) {
+        throw new Error(error.message);
+    }
+    throw new Error("Unknown CLI error");
+}

package/dist/config/agentPolicies.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultPolicyConfig = createDefaultPolicyConfig;
+const web3_js_1 = require("@solana/web3.js");
+const programs_1 = require("../solana/programs");
+const env_1 = require("./env");
+function createDefaultPolicyConfig(input) {
+    const ttlMinutes = (0, env_1.getPolicySessionTtlMinutes)();
+    return {
+        agentId: input.agentId,
+        approvalMode: input.approvalMode ?? "sandbox",
+        sessionExpiresAtIso8601: new Date(Date.now() + ttlMinutes * 60_000).toISOString(),
+        limits: {
+            maxSolPerTxLamports: input.maxSolPerTxLamports ?? 1_000_000_000,
+            maxSplPerTxRawAmount: input.maxSplPerTxRawAmount ?? 1000000000n,
+            maxTransactionsPerSession: input.maxTransactionsPerSession ?? 50,
+            maxTransactionsPerDay: input.maxTransactionsPerDay ?? 500
+        },
+        rules: {
+            allowOpaqueProgramIds: input.allowOpaqueProgramIds ?? [],
+            allowedCloseAccountDestinations: input.allowedCloseAccountDestinations,
+            allowedProgramIds: [
+                web3_js_1.SystemProgram.programId.toBase58(),
+                programs_1.TOKEN_PROGRAM_ID.toBase58(),
+                programs_1.ASSOCIATED_TOKEN_PROGRAM_ID.toBase58(),
+                programs_1.MEMO_PROGRAM_ID.toBase58(),
+                ...(input.extraAllowedProgramIds ?? []),
+                ...(0, env_1.getExtraWhitelistedPrograms)()
+            ],
+            allowedMintAddresses: input.allowedMints ?? [],
+            allowedTransferDestinations: input.allowedTransferDestinations,
+            denyUnknownInstructionsByDefault: true,
+            requireSimulationSuccess: true,
+            rejectSuspiciousBalanceDeltas: true
+        }
+    };
+}

package/dist/config/env.js

@@ -0,0 +1,249 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvConfigError = void 0;
+exports.getOptionalSecretKey = getOptionalSecretKey;
+exports.getOptionalDevnetTreasurySecretKey = getOptionalDevnetTreasurySecretKey;
+exports.getRpcUrl = getRpcUrl;
+exports.getRpcFallbackUrl = getRpcFallbackUrl;
+exports.getKoraRpcUrl = getKoraRpcUrl;
+exports.isKoraMockMode = isKoraMockMode;
+exports.getJupiterApiBaseUrl = getJupiterApiBaseUrl;
+exports.getRaydiumLpConfigPath = getRaydiumLpConfigPath;
+exports.getKaminoLiveConfigPath = getKaminoLiveConfigPath;
+exports.isLiveSwapPathEnabled = isLiveSwapPathEnabled;
+exports.isLiveRaydiumLpEnabled = isLiveRaydiumLpEnabled;
+exports.isLiveKaminoEnabled = isLiveKaminoEnabled;
+exports.isLiveMarinadeEnabled = isLiveMarinadeEnabled;
+exports.isUniversalDeFiLiveFirstEnabled = isUniversalDeFiLiveFirstEnabled;
+exports.getUsdcMintAddress = getUsdcMintAddress;
+exports.getExtraWhitelistedPrograms = getExtraWhitelistedPrograms;
+exports.getPolicySessionTtlMinutes = getPolicySessionTtlMinutes;
+exports.getRemoteSignerConfig = getRemoteSignerConfig;
+exports.detectClusterFromRpcUrl = detectClusterFromRpcUrl;
+exports.assertMintMatchesRpcCluster = assertMintMatchesRpcCluster;
+exports.redactSecretForLogs = redactSecretForLogs;
+const dotenv_1 = __importDefault(require("dotenv"));
+const web3_js_1 = require("@solana/web3.js");
+dotenv_1.default.config();
+const PRIVATE_KEY_ENV = "AGENT_PRIVATE_KEY";
+const RPC_ENV = "SOLANA_RPC_URL";
+const RPC_FALLBACK_ENV = "SOLANA_RPC_FALLBACK_URL";
+const KORA_RPC_ENV = "KORA_RPC_URL";
+const KORA_MOCK_MODE_ENV = "KORA_MOCK_MODE";
+const JUPITER_API_BASE_URL_ENV = "JUPITER_API_BASE_URL";
+const ENABLE_LIVE_SWAP_PATH_ENV = "ENABLE_LIVE_SWAP_PATH";
+const ENABLE_LIVE_RAYDIUM_LP_ENV = "ENABLE_LIVE_RAYDIUM_LP";
+const ENABLE_LIVE_KAMINO_ENV = "ENABLE_LIVE_KAMINO";
+const ENABLE_LIVE_MARINADE_ENV = "ENABLE_LIVE_MARINADE";
+const RAYDIUM_LP_CONFIG_PATH_ENV = "RAYDIUM_LP_CONFIG_PATH";
+const KAMINO_LIVE_CONFIG_PATH_ENV = "KAMINO_LIVE_CONFIG_PATH";
+const UNIVERSAL_DEFI_LIVE_FIRST_ENV = "UNIVERSAL_DEFI_LIVE_FIRST";
+const USDC_MINT_ENV = "USDC_MINT";
+const EXTRA_WHITELISTED_PROGRAMS_ENV = "EXTRA_WHITELISTED_PROGRAMS";
+const POLICY_SESSION_TTL_MINUTES_ENV = "POLICY_SESSION_TTL_MINUTES";
+const DEVNET_TREASURY_PRIVATE_KEY_ENV = "DEVNET_TREASURY_PRIVATE_KEY";
+const REMOTE_SIGNER_URL_ENV = "REMOTE_SIGNER_URL";
+const REMOTE_SIGNER_BEARER_TOKEN_ENV = "REMOTE_SIGNER_BEARER_TOKEN";
+const REMOTE_SIGNER_PUBKEY_ENV = "REMOTE_SIGNER_PUBKEY";
+const MAINNET_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+const DEVNET_USDC_MINT = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
+class EnvConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EnvConfigError";
+    }
+}
+exports.EnvConfigError = EnvConfigError;
+function parseSecretKey(rawValue) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawValue);
+    }
+    catch {
+        throw new EnvConfigError(`${PRIVATE_KEY_ENV} must be valid JSON.`);
+    }
+    if (!Array.isArray(parsed) || !parsed.every((value) => Number.isInteger(value))) {
+        throw new EnvConfigError(`${PRIVATE_KEY_ENV} must be a JSON array of integers.`);
+    }
+    if (parsed.length !== 64) {
+        throw new EnvConfigError(`${PRIVATE_KEY_ENV} must contain exactly 64 integers.`);
+    }
+    const byteValues = parsed;
+    if (byteValues.some((value) => value < 0 || value > 255)) {
+        throw new EnvConfigError(`${PRIVATE_KEY_ENV} values must be between 0 and 255.`);
+    }
+    return Uint8Array.from(byteValues);
+}
+function getOptionalSecretKeyFromEnv(envName) {
+    const rawValue = process.env[envName];
+    if (!rawValue) {
+        return null;
+    }
+    const trimmed = rawValue.trim();
+    if (trimmed.length === 0 || trimmed === "[]") {
+        return null;
+    }
+    return parseSecretKey(trimmed);
+}
+function getOptionalSecretKey() {
+    return getOptionalSecretKeyFromEnv(PRIVATE_KEY_ENV);
+}
+function getOptionalDevnetTreasurySecretKey() {
+    return getOptionalSecretKeyFromEnv(DEVNET_TREASURY_PRIVATE_KEY_ENV);
+}
+function getRpcUrl() {
+    const rpcUrl = process.env[RPC_ENV]?.trim();
+    return rpcUrl && rpcUrl.length > 0 ? rpcUrl : "https://api.devnet.solana.com";
+}
+function getRpcFallbackUrl() {
+    const fallbackUrl = process.env[RPC_FALLBACK_ENV]?.trim();
+    return fallbackUrl && fallbackUrl.length > 0 ? fallbackUrl : null;
+}
+function getKoraRpcUrl() {
+    const koraRpcUrl = process.env[KORA_RPC_ENV]?.trim();
+    return koraRpcUrl && koraRpcUrl.length > 0
+        ? koraRpcUrl
+        : "https://kora.devnet.lazorkit.com";
+}
+function isKoraMockMode() {
+    const rawValue = process.env[KORA_MOCK_MODE_ENV]?.trim().toLowerCase();
+    if (!rawValue) {
+        return true;
+    }
+    return rawValue !== "false" && rawValue !== "0";
+}
+function getJupiterApiBaseUrl() {
+    const value = process.env[JUPITER_API_BASE_URL_ENV]?.trim();
+    return value && value.length > 0 ? value : "https://lite-api.jup.ag";
+}
+function getRaydiumLpConfigPath() {
+    const value = process.env[RAYDIUM_LP_CONFIG_PATH_ENV]?.trim();
+    return value && value.length > 0 ? value : "raydium_lp.devnet.json";
+}
+function getKaminoLiveConfigPath() {
+    const value = process.env[KAMINO_LIVE_CONFIG_PATH_ENV]?.trim();
+    return value && value.length > 0 ? value : "kamino_live.json";
+}
+function isLiveSwapPathEnabled() {
+    const rawValue = process.env[ENABLE_LIVE_SWAP_PATH_ENV]?.trim().toLowerCase();
+    if (!rawValue) {
+        return false;
+    }
+    return rawValue === "true" || rawValue === "1";
+}
+function isLiveRaydiumLpEnabled() {
+    const rawValue = process.env[ENABLE_LIVE_RAYDIUM_LP_ENV]?.trim().toLowerCase();
+    if (!rawValue) {
+        return false;
+    }
+    return rawValue === "true" || rawValue === "1";
+}
+function isLiveKaminoEnabled() {
+    const rawValue = process.env[ENABLE_LIVE_KAMINO_ENV]?.trim().toLowerCase();
+    if (!rawValue) {
+        return false;
+    }
+    return rawValue === "true" || rawValue === "1";
+}
+function isLiveMarinadeEnabled() {
+    const rawValue = process.env[ENABLE_LIVE_MARINADE_ENV]?.trim().toLowerCase();
+    if (!rawValue) {
+        return false;
+    }
+    return rawValue === "true" || rawValue === "1";
+}
+function isUniversalDeFiLiveFirstEnabled() {
+    const rawValue = process.env[UNIVERSAL_DEFI_LIVE_FIRST_ENV]?.trim().toLowerCase();
+    if (!rawValue) {
+        return true;
+    }
+    return rawValue !== "false" && rawValue !== "0";
+}
+function getUsdcMintAddress() {
+    const value = process.env[USDC_MINT_ENV]?.trim();
+    return value && value.length > 0
+        ? value
+        : DEVNET_USDC_MINT;
+}
+function getExtraWhitelistedPrograms() {
+    const value = process.env[EXTRA_WHITELISTED_PROGRAMS_ENV]?.trim();
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function getPolicySessionTtlMinutes() {
+    const rawValue = process.env[POLICY_SESSION_TTL_MINUTES_ENV]?.trim();
+    if (!rawValue) {
+        return 60;
+    }
+    const ttl = Number(rawValue);
+    if (!Number.isInteger(ttl) || ttl <= 0 || ttl > 24 * 60) {
+        throw new EnvConfigError(`${POLICY_SESSION_TTL_MINUTES_ENV} must be a positive integer between 1 and 1440.`);
+    }
+    return ttl;
+}
+function getRemoteSignerConfig() {
+    const url = process.env[REMOTE_SIGNER_URL_ENV]?.trim();
+    const bearerToken = process.env[REMOTE_SIGNER_BEARER_TOKEN_ENV]?.trim();
+    const publicKeyValue = process.env[REMOTE_SIGNER_PUBKEY_ENV]?.trim();
+    const configuredCount = [url, bearerToken, publicKeyValue].filter((value) => value && value.length > 0).length;
+    if (configuredCount === 0) {
+        return null;
+    }
+    if (configuredCount !== 3 || !url || !bearerToken || !publicKeyValue) {
+        throw new EnvConfigError(`${REMOTE_SIGNER_URL_ENV}, ${REMOTE_SIGNER_BEARER_TOKEN_ENV}, and ${REMOTE_SIGNER_PUBKEY_ENV} must all be configured together.`);
+    }
+    let publicKey;
+    try {
+        publicKey = new web3_js_1.PublicKey(publicKeyValue);
+    }
+    catch {
+        throw new EnvConfigError(`${REMOTE_SIGNER_PUBKEY_ENV} must be a valid Solana public key.`);
+    }
+    return {
+        bearerToken,
+        publicKey,
+        url
+    };
+}
+function detectClusterFromRpcUrl(rpcUrl) {
+    const normalized = rpcUrl.trim().toLowerCase();
+    if (normalized.includes("localhost") ||
+        normalized.includes("127.0.0.1") ||
+        normalized.includes("0.0.0.0")) {
+        return "localnet";
+    }
+    if (normalized.includes("devnet")) {
+        return "devnet";
+    }
+    if (normalized.includes("testnet")) {
+        return "testnet";
+    }
+    if (normalized.includes("mainnet")) {
+        return "mainnet-beta";
+    }
+    return "unknown";
+}
+function assertMintMatchesRpcCluster(input) {
+    const cluster = detectClusterFromRpcUrl(input.rpcUrl);
+    if (cluster === "unknown" || cluster === "localnet" || cluster === "testnet") {
+        return;
+    }
+    const mint = input.mintAddress.trim();
+    if (cluster === "devnet" && mint === MAINNET_USDC_MINT) {
+        throw new EnvConfigError(`${input.mintName} is set to the mainnet mint (${MAINNET_USDC_MINT}) while RPC is devnet (${input.rpcUrl}). Set USDC_MINT to a devnet mint such as ${DEVNET_USDC_MINT}.`);
+    }
+    if (cluster === "mainnet-beta" && mint === DEVNET_USDC_MINT) {
+        throw new EnvConfigError(`${input.mintName} is set to the devnet mint (${DEVNET_USDC_MINT}) while RPC is mainnet (${input.rpcUrl}). Set USDC_MINT to the mainnet mint ${MAINNET_USDC_MINT}.`);
+    }
+}
+function redactSecretForLogs() {
+    return `[REDACTED:${PRIVATE_KEY_ENV}]`;
+}

package/dist/config/policyPresets.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_POLICY_PRESET = exports.POLICY_PRESETS = void 0;
+exports.listPolicyPresetSummaries = listPolicyPresetSummaries;
+exports.resolvePolicyConfig = resolvePolicyConfig;
+const agentPolicies_1 = require("./agentPolicies");
+exports.POLICY_PRESETS = {
+    "observe-only": {
+        label: "Observe Only",
+        description: "Blocks broadcasts while still allowing inspection and monitoring.",
+        build: ({ agentId }) => (0, agentPolicies_1.createDefaultPolicyConfig)({
+            agentId,
+            maxTransactionsPerDay: 0,
+            maxTransactionsPerSession: 0
+        })
+    },
+    "simulate-only": {
+        label: "Simulate Only",
+        description: "Safe simulation-first mode with conservative limits for testing.",
+        build: ({ agentId }) => (0, agentPolicies_1.createDefaultPolicyConfig)({
+            agentId,
+            maxSolPerTxLamports: 100_000_000,
+            maxSplPerTxRawAmount: 100000000n,
+            maxTransactionsPerDay: 25,
+            maxTransactionsPerSession: 5
+        })
+    },
+    "auto-devnet-safe": {
+        label: "Auto Devnet Safe",
+        description: "Default autonomous devnet profile with conservative per-tx and per-session limits.",
+        build: ({ agentId }) => (0, agentPolicies_1.createDefaultPolicyConfig)({
+            agentId,
+            maxSolPerTxLamports: 300_000_000,
+            maxSplPerTxRawAmount: 1000000000n,
+            maxTransactionsPerDay: 20,
+            maxTransactionsPerSession: 5
+        })
+    },
+    "guarded-live": {
+        label: "Guarded Live",
+        description: "Manual-approval profile for higher-risk live execution.",
+        build: ({ agentId }) => (0, agentPolicies_1.createDefaultPolicyConfig)({
+            agentId,
+            approvalMode: "live",
+            maxSolPerTxLamports: 1_000_000_000,
+            maxSplPerTxRawAmount: 5000000000n,
+            maxTransactionsPerDay: 50,
+            maxTransactionsPerSession: 10
+        })
+    },
+    custom: {
+        label: "Custom",
+        description: "Custom policy built from provider defaults plus explicit overrides.",
+        build: ({ agentId }) => (0, agentPolicies_1.createDefaultPolicyConfig)({ agentId })
+    }
+};
+exports.DEFAULT_POLICY_PRESET = "auto-devnet-safe";
+function listPolicyPresetSummaries() {
+    return Object.entries(exports.POLICY_PRESETS).map(([name, preset]) => ({
+        description: preset.description,
+        label: preset.label,
+        name
+    }));
+}
+function resolvePolicyConfig(input) {
+    const base = exports.POLICY_PRESETS[input.presetName].build({
+        agentId: input.agentId
+    });
+    const overrides = input.overrides;
+    if (!overrides) {
+        return base;
+    }
+    const ttlMinutes = overrides.sessionTtlMinutes ?? null;
+    const sessionExpiresAtIso8601 = ttlMinutes === null
+        ? base.sessionExpiresAtIso8601
+        : new Date(Date.now() + ttlMinutes * 60_000).toISOString();
+    return {
+        ...base,
+        approvalMode: overrides.approvalMode ?? base.approvalMode,
+        sessionExpiresAtIso8601,
+        limits: {
+            ...base.limits,
+            maxSolPerTxLamports: overrides.maxSolPerTxLamports ?? base.limits.maxSolPerTxLamports,
+            maxSplPerTxRawAmount: overrides.maxSplPerTxRawAmount !== undefined
+                ? BigInt(overrides.maxSplPerTxRawAmount)
+                : base.limits.maxSplPerTxRawAmount,
+            maxTransactionsPerDay: overrides.maxTransactionsPerDay ?? base.limits.maxTransactionsPerDay,
+            maxTransactionsPerSession: overrides.maxTransactionsPerSession ?? base.limits.maxTransactionsPerSession
+        },
+        rules: {
+            ...base.rules,
+            allowOpaqueProgramIds: overrides.allowOpaqueProgramIds ?? base.rules.allowOpaqueProgramIds,
+            allowedCloseAccountDestinations: overrides.allowedCloseAccountDestinations ?? base.rules.allowedCloseAccountDestinations,
+            allowedMintAddresses: overrides.allowedMints ?? base.rules.allowedMintAddresses,
+            allowedProgramIds: [
+                ...base.rules.allowedProgramIds,
+                ...(overrides.extraAllowedProgramIds ?? [])
+            ],
+            allowedTransferDestinations: overrides.allowedTransferDestinations ?? base.rules.allowedTransferDestinations,
+            denyUnknownInstructionsByDefault: overrides.denyUnknownInstructionsByDefault ?? base.rules.denyUnknownInstructionsByDefault,
+            rejectSuspiciousBalanceDeltas: overrides.rejectSuspiciousBalanceDeltas ?? base.rules.rejectSuspiciousBalanceDeltas,
+            requireSimulationSuccess: overrides.requireSimulationSuccess ?? base.rules.requireSimulationSuccess
+        }
+    };
+}

package/dist/core/balances/BalanceService.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BalanceService = void 0;
+const LAMPORTS_PER_SOL = 1_000_000_000;
+class BalanceService {
+    rpcClient;
+    tokenService;
+    constructor(rpcClient, tokenService) {
+        this.rpcClient = rpcClient;
+        this.tokenService = tokenService;
+    }
+    async getSolBalanceLamports(owner) {
+        return this.rpcClient.getBalance(owner, "confirmed");
+    }
+    async getSolBalance(owner) {
+        const lamports = await this.getSolBalanceLamports(owner);
+        return lamports / LAMPORTS_PER_SOL;
+    }
+    async getSplTokenBalance(input) {
+        const ata = this.tokenService.findAssociatedTokenAddress(input.owner, input.mint);
+        const account = await this.rpcClient.getAccountInfo(ata, "confirmed");
+        if (!account) {
+            return 0;
+        }
+        const tokenBalance = await this.rpcClient.getTokenAccountBalance(ata, "confirmed");
+        if (tokenBalance.value.uiAmount !== null && tokenBalance.value.uiAmount !== undefined) {
+            return tokenBalance.value.uiAmount;
+        }
+        const decimals = tokenBalance.value.decimals;
+        const raw = Number(tokenBalance.value.amount);
+        return raw / 10 ** decimals;
+    }
+}
+exports.BalanceService = BalanceService;

package/dist/core/funding/DevnetFundingService.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevnetFundingService = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const env_1 = require("../../config/env");
+const WalletManager_1 = require("../wallet/WalletManager");
+class DevnetFundingService {
+    rpcClient;
+    transactionService;
+    treasuryWallet;
+    constructor(rpcClient, transactionService, treasuryWallet = loadTreasuryWalletFromEnv()) {
+        this.rpcClient = rpcClient;
+        this.transactionService = transactionService;
+        this.treasuryWallet = treasuryWallet;
+    }
+    hasTreasuryWallet() {
+        return this.treasuryWallet !== null;
+    }
+    getTreasuryPublicKey() {
+        return this.treasuryWallet?.publicKey ?? null;
+    }
+    async ensureMinimumSol(input) {
+        const currentBalance = await input.balanceService.getSolBalance(input.recipient);
+        if (currentBalance >= input.minimumSol) {
+            return null;
+        }
+        const amountSol = roundSolAmount(input.minimumSol - currentBalance);
+        if (this.canUseTreasury(input.recipient)) {
+            return this.fundFromTreasury({
+                amountSol,
+                recipient: input.recipient
+            });
+        }
+        return this.requestAirdrop({
+            amountSol: input.airdropAmountSol ?? Math.max(amountSol, 1),
+            recipient: input.recipient
+        });
+    }
+    async fundExactSol(input) {
+        if (this.canUseTreasury(input.recipient)) {
+            return this.fundFromTreasury(input);
+        }
+        return this.requestAirdrop(input);
+    }
+    async waitForMinimumBalance(input) {
+        const attempts = input.attempts ?? 10;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            const updatedBalance = await input.balanceService.getSolBalance(input.recipient);
+            if (updatedBalance >= input.minimumSol) {
+                return updatedBalance;
+            }
+            await delay(1_000);
+        }
+        return input.balanceService.getSolBalance(input.recipient);
+    }
+    canUseTreasury(recipient) {
+        return (this.treasuryWallet !== null &&
+            !this.treasuryWallet.publicKey.equals(recipient));
+    }
+    async fundFromTreasury(input) {
+        if (!this.treasuryWallet) {
+            throw new Error("Treasury wallet is not configured.");
+        }
+        const built = await this.transactionService.buildTransaction({
+            feePayer: this.treasuryWallet.publicKey,
+            instructions: [
+                this.transactionService.buildSolTransferInstructionInSol({
+                    amountSol: input.amountSol,
+                    from: this.treasuryWallet.publicKey,
+                    to: input.recipient
+                })
+            ],
+            signer: this.treasuryWallet
+        });
+        const send = await this.transactionService.sendAndConfirm(built);
+        return {
+            signature: send.signature,
+            source: "treasury-transfer"
+        };
+    }
+    async requestAirdrop(input) {
+        const signature = await this.rpcClient.requestAirdrop(input.recipient, Math.round(input.amountSol * web3_js_1.LAMPORTS_PER_SOL));
+        await this.rpcClient.confirmTransaction(signature, "confirmed");
+        return {
+            signature,
+            source: "airdrop"
+        };
+    }
+}
+exports.DevnetFundingService = DevnetFundingService;
+function loadTreasuryWalletFromEnv() {
+    const secretKey = (0, env_1.getOptionalDevnetTreasurySecretKey)();
+    if (!secretKey) {
+        return null;
+    }
+    return WalletManager_1.WalletManager.fromSecretKey(secretKey, "env");
+}
+function roundSolAmount(amountSol) {
+    return Math.max(0, Math.round(amountSol * web3_js_1.LAMPORTS_PER_SOL) / web3_js_1.LAMPORTS_PER_SOL);
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/core/idempotency/ExecutionIdempotencyGuard.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionIdempotencyGuard = void 0;
+const crypto_1 = require("crypto");
+const DEFAULT_MAX_ENTRIES = 1000;
+const DEFAULT_TTL_MS = 10 * 60 * 1000; // 10 minutes
+/**
+ * Prevents duplicate execution of the same intent by tracking unique execution IDs.
+ * Uses a bounded in-memory set with TTL-based expiry.
+ */
+class ExecutionIdempotencyGuard {
+    entries = new Map();
+    maxEntries;
+    ttlMs;
+    cleanupCounter = 0;
+    cleanupInterval = 50;
+    constructor(options) {
+        this.maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
+    }
+    /**
+     * Generate a new unique execution ID.
+     */
+    generateId() {
+        return (0, crypto_1.randomUUID)();
+    }
+    /**
+     * Attempt to acquire a lock for the given execution ID.
+     * Returns `true` on the first call for a given ID (execution allowed).
+     * Returns `false` if the ID has already been acquired (duplicate blocked).
+     */
+    acquire(executionId) {
+        this.maybeCleanup();
+        const existing = this.entries.get(executionId);
+        if (existing && existing.expiresAt > Date.now()) {
+            return false;
+        }
+        if (this.entries.size >= this.maxEntries) {
+            this.evictOldest();
+        }
+        this.entries.set(executionId, {
+            id: executionId,
+            expiresAt: Date.now() + this.ttlMs
+        });
+        return true;
+    }
+    /**
+     * Check whether an execution ID has already been acquired (without acquiring it).
+     */
+    has(executionId) {
+        const existing = this.entries.get(executionId);
+        if (!existing) {
+            return false;
+        }
+        if (existing.expiresAt <= Date.now()) {
+            this.entries.delete(executionId);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Returns the number of active (non-expired) tracked entries.
+     */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Remove all tracked entries.
+     */
+    clear() {
+        this.entries.clear();
+    }
+    maybeCleanup() {
+        this.cleanupCounter += 1;
+        if (this.cleanupCounter < this.cleanupInterval) {
+            return;
+        }
+        this.cleanupCounter = 0;
+        const now = Date.now();
+        for (const [id, entry] of this.entries) {
+            if (entry.expiresAt <= now) {
+                this.entries.delete(id);
+            }
+        }
+    }
+    evictOldest() {
+        let oldestId = null;
+        let oldestExpiry = Infinity;
+        for (const [id, entry] of this.entries) {
+            if (entry.expiresAt < oldestExpiry) {
+                oldestExpiry = entry.expiresAt;
+                oldestId = id;
+            }
+        }
+        if (oldestId) {
+            this.entries.delete(oldestId);
+        }
+    }
+}
+exports.ExecutionIdempotencyGuard = ExecutionIdempotencyGuard;