@prktsol/prkt 1.0.0 → 1.0.1

package/dist/compression/AuditLogManager.d.ts

@@ -0,0 +1,9 @@
+import { AuditEntry } from "./types";
+export declare class AuditLogManager {
+    private readonly rpcEndpoint;
+    private static readonly auditRegistry;
+    constructor(rpcEndpoint: string);
+    appendAuditEntry(entry: AuditEntry, payer: import("@solana/web3.js").Keypair): Promise<string>;
+    fetchAuditLog(agentId: string, limit?: number): Promise<AuditEntry[]>;
+    private getStore;
+}

package/dist/compression/AuditLogManager.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditLogManager = void 0;
+const crypto_1 = require("crypto");
+const PRKTError_1 = require("../errors/PRKTError");
+const CompressedDataAccount_1 = require("../zkCompression/CompressedDataAccount");
+const AUDIT_ACCOUNT_DISCRIMINATOR = "PRKTAUD1";
+class AuditLogManager {
+    rpcEndpoint;
+    static auditRegistry = new Map();
+    constructor(rpcEndpoint) {
+        this.rpcEndpoint = rpcEndpoint;
+    }
+    async appendAuditEntry(entry, payer) {
+        try {
+            const payload = serializeAuditEntry(entry);
+            const signature = await this.getStore().writeAccount({
+                discriminator: AUDIT_ACCOUNT_DISCRIMINATOR,
+                namespace: "prkt-audit",
+                parts: [entry.agentId, entry.timestamp.toString(), hashAuditEntry(entry)],
+                payer,
+                payload
+            });
+            const existing = AuditLogManager.auditRegistry.get(entry.agentId) ?? [];
+            existing.push(entry);
+            existing.sort((left, right) => left.timestamp - right.timestamp);
+            AuditLogManager.auditRegistry.set(entry.agentId, existing);
+            return signature.signature;
+        }
+        catch (error) {
+            throw new PRKTError_1.CompressionError(`Failed to append audit entry: ${error}`);
+        }
+    }
+    async fetchAuditLog(agentId, limit) {
+        try {
+            const inMemory = AuditLogManager.auditRegistry.get(agentId);
+            if (inMemory && inMemory.length > 0) {
+                return [...inMemory].slice(-(limit ?? inMemory.length));
+            }
+            const records = await this.getStore().findAccountsByOwner({
+                discriminator: AUDIT_ACCOUNT_DISCRIMINATOR
+            });
+            const entries = records
+                .map((record) => record.payload)
+                .filter((payload) => !!payload && payload.a === agentId)
+                .map(deserializeAuditEntry)
+                .sort((left, right) => left.timestamp - right.timestamp);
+            AuditLogManager.auditRegistry.set(agentId, entries);
+            return limit ? entries.slice(-limit) : entries;
+        }
+        catch (error) {
+            throw new PRKTError_1.CompressionError(`Failed to fetch audit log: ${error}`);
+        }
+    }
+    getStore() {
+        return new CompressedDataAccount_1.CompressedDataAccount(this.rpcEndpoint);
+    }
+}
+exports.AuditLogManager = AuditLogManager;
+function serializeAuditEntry(entry) {
+    return {
+        a: entry.agentId,
+        i: entry.intentType,
+        ok: entry.approved ? 1 : 0,
+        r: entry.rejectionReason,
+        s: entry.simulationResult,
+        t: entry.timestamp,
+        tx: entry.txSignature
+    };
+}
+function deserializeAuditEntry(payload) {
+    return {
+        agentId: payload.a,
+        approved: payload.ok === 1,
+        intentType: payload.i,
+        rejectionReason: payload.r,
+        simulationResult: payload.s,
+        timestamp: payload.t,
+        txSignature: payload.tx
+    };
+}
+function hashAuditEntry(entry) {
+    return (0, crypto_1.createHash)("sha256")
+        .update(JSON.stringify(serializeAuditEntry(entry)), "utf8")
+        .digest("hex");
+}

package/dist/compression/PolicyAccountManager.d.ts

@@ -0,0 +1,11 @@
+import { Keypair } from "@solana/web3.js";
+import { CompressedPolicyState } from "./types";
+export declare class PolicyAccountManager {
+    private readonly rpcEndpoint;
+    private static readonly policyRegistry;
+    constructor(rpcEndpoint: string);
+    createCompressedPolicyAccount(agentId: string, policy: Omit<CompressedPolicyState, "agentId">, payer: Keypair): Promise<string>;
+    fetchCompressedPolicyAccount(agentId: string): Promise<CompressedPolicyState>;
+    updateCompressedPolicyAccount(agentId: string, updates: Partial<CompressedPolicyState>, payer: Keypair): Promise<string>;
+    private getStore;
+}

package/dist/compression/PolicyAccountManager.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyAccountManager = void 0;
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const PRKTError_1 = require("../errors/PRKTError");
+const CompressedDataAccount_1 = require("../zkCompression/CompressedDataAccount");
+const POLICY_ACCOUNT_DISCRIMINATOR = "PRKTPOL1";
+class PolicyAccountManager {
+    rpcEndpoint;
+    static policyRegistry = new Map();
+    constructor(rpcEndpoint) {
+        this.rpcEndpoint = rpcEndpoint;
+    }
+    async createCompressedPolicyAccount(agentId, policy, payer) {
+        try {
+            const state = {
+                agentId,
+                ...policy
+            };
+            const updatedAt = Date.now();
+            const record = await this.getStore().writeAccount({
+                discriminator: POLICY_ACCOUNT_DISCRIMINATOR,
+                namespace: "prkt-policy",
+                parts: [agentId, updatedAt.toString()],
+                payer,
+                payload: serializePolicy(state, updatedAt)
+            });
+            PolicyAccountManager.policyRegistry.set(agentId, state);
+            return record.signature;
+        }
+        catch (error) {
+            throw new PRKTError_1.CompressionError(`Failed to create compressed policy account: ${error}`);
+        }
+    }
+    async fetchCompressedPolicyAccount(agentId) {
+        try {
+            const inMemory = PolicyAccountManager.policyRegistry.get(agentId);
+            if (inMemory) {
+                return inMemory;
+            }
+            const records = await this.getStore().findAccountsByOwner({
+                discriminator: POLICY_ACCOUNT_DISCRIMINATOR
+            });
+            const payload = records
+                .map((record) => record.payload)
+                .filter((value) => !!value && value.a === agentId)
+                .sort((left, right) => right.u - left.u)[0];
+            if (payload) {
+                const policy = deserializePolicy(payload);
+                PolicyAccountManager.policyRegistry.set(agentId, policy);
+                return policy;
+            }
+            throw new Error(`policy not found for ${agentId}`);
+        }
+        catch (error) {
+            throw new PRKTError_1.CompressionError(`Failed to fetch compressed policy account: ${error}`);
+        }
+    }
+    async updateCompressedPolicyAccount(agentId, updates, payer) {
+        try {
+            const current = await this.fetchCompressedPolicyAccount(agentId);
+            const merged = {
+                ...current,
+                ...updates,
+                agentId,
+                dailySpendLimit: updates.dailySpendLimit ?? current.dailySpendLimit,
+                programAllowlist: updates.programAllowlist ?? current.programAllowlist,
+                spentToday: updates.spentToday ?? current.spentToday
+            };
+            const updatedAt = Date.now();
+            const record = await this.getStore().writeAccount({
+                discriminator: POLICY_ACCOUNT_DISCRIMINATOR,
+                namespace: "prkt-policy",
+                parts: [agentId, updatedAt.toString()],
+                payer,
+                payload: serializePolicy(merged, updatedAt)
+            });
+            PolicyAccountManager.policyRegistry.set(agentId, merged);
+            return record.signature;
+        }
+        catch (error) {
+            throw new PRKTError_1.CompressionError(`Failed to update compressed policy account: ${error}`);
+        }
+    }
+    getStore() {
+        return new CompressedDataAccount_1.CompressedDataAccount(this.rpcEndpoint);
+    }
+}
+exports.PolicyAccountManager = PolicyAccountManager;
+function serializePolicy(policy, updatedAt) {
+    return {
+        a: policy.agentId,
+        d: policy.dailySpendLimit.toString(),
+        k: policy.killSwitchActive ? 1 : 0,
+        l: policy.programAllowlist.map((programId) => programId.toBase58()),
+        r: policy.lastResetTimestamp,
+        s: policy.sessionTTL,
+        t: policy.spentToday.toString(),
+        u: updatedAt
+    };
+}
+function deserializePolicy(payload) {
+    return {
+        agentId: payload.a,
+        dailySpendLimit: new anchor_1.BN(payload.d),
+        killSwitchActive: payload.k === 1,
+        lastResetTimestamp: payload.r,
+        programAllowlist: payload.l.map((programId) => new web3_js_1.PublicKey(programId)),
+        sessionTTL: payload.s,
+        spentToday: new anchor_1.BN(payload.t)
+    };
+}

package/dist/compression/types.d.ts

@@ -0,0 +1,20 @@
+import { PublicKey } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+export interface CompressedPolicyState {
+    agentId: string;
+    dailySpendLimit: BN;
+    sessionTTL: number;
+    programAllowlist: PublicKey[];
+    killSwitchActive: boolean;
+    spentToday: BN;
+    lastResetTimestamp: number;
+}
+export interface AuditEntry {
+    agentId: string;
+    timestamp: number;
+    intentType: string;
+    approved: boolean;
+    rejectionReason?: string;
+    simulationResult: string;
+    txSignature?: string;
+}

package/dist/compression/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/config/PRKTConfig.d.ts

@@ -0,0 +1,17 @@
+export interface PRKTConfig {
+    zkCompression: {
+        enabled: boolean;
+        rpcEndpoint: string;
+    };
+    dataAnchoring: {
+        enabled: boolean;
+    };
+    zkPolicyProofs: {
+        enabled: boolean;
+    };
+    evmAdapters: {
+        enabled: boolean;
+        neonRpcEndpoint: string;
+    };
+}
+export declare const defaultPRKTConfig: PRKTConfig;

package/dist/config/PRKTConfig.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultPRKTConfig = void 0;
+exports.defaultPRKTConfig = {
+    zkCompression: {
+        enabled: false,
+        rpcEndpoint: "https://devnet.helius-rpc.com/?api-key=" // Default placeholder or use env later
+    },
+    dataAnchoring: {
+        enabled: false
+    },
+    zkPolicyProofs: {
+        enabled: false
+    },
+    evmAdapters: {
+        enabled: false,
+        neonRpcEndpoint: "https://devnet.neonevm.org"
+    }
+};

package/dist/config/agentPolicies.d.ts

@@ -0,0 +1,14 @@
+import type { PolicyConfig } from "../policy";
+export declare function createDefaultPolicyConfig(input: {
+    agentId: string;
+    allowOpaqueProgramIds?: string[];
+    allowedCloseAccountDestinations?: string[];
+    allowedMints?: string[];
+    extraAllowedProgramIds?: string[];
+    allowedTransferDestinations?: string[];
+    approvalMode?: "sandbox" | "live";
+    maxSolPerTxLamports?: number;
+    maxSplPerTxRawAmount?: bigint;
+    maxTransactionsPerSession?: number;
+    maxTransactionsPerDay?: number;
+}): PolicyConfig;

package/dist/config/env.d.ts

@@ -0,0 +1,39 @@
+import { PublicKey } from "@solana/web3.js";
+export declare class EnvConfigError extends Error {
+    constructor(message: string);
+}
+export declare function getOptionalSecretKey(): Uint8Array | null;
+export declare function getOptionalDevnetTreasurySecretKey(): Uint8Array | null;
+export declare function getRpcUrl(): string;
+export declare function getRpcFallbackUrl(): string | null;
+export declare function getZkCompressionApiUrl(): string | null;
+export declare function getZkProverUrl(): string | null;
+export declare function getOnchainPolicyGuardProgramId(): string | null;
+export declare function getImplementationPath(): string;
+export declare function isDefensibleDevnetDemoMode(): boolean;
+export declare function isNeonBroadcastEnabled(): boolean;
+export declare function getKoraRpcUrl(): string;
+export declare function isKoraMockMode(): boolean;
+export declare function getJupiterApiBaseUrl(): string;
+export declare function getRaydiumLpConfigPath(): string;
+export declare function getKaminoLiveConfigPath(): string;
+export declare function isLiveSwapPathEnabled(): boolean;
+export declare function isLiveRaydiumLpEnabled(): boolean;
+export declare function isLiveKaminoEnabled(): boolean;
+export declare function isLiveMarinadeEnabled(): boolean;
+export declare function isUniversalDeFiLiveFirstEnabled(): boolean;
+export declare function getUsdcMintAddress(): string;
+export declare function getExtraWhitelistedPrograms(): string[];
+export declare function getPolicySessionTtlMinutes(): number;
+export declare function getRemoteSignerConfig(): {
+    bearerToken: string;
+    publicKey: PublicKey;
+    url: string;
+} | null;
+export declare function detectClusterFromRpcUrl(rpcUrl: string): "mainnet-beta" | "devnet" | "testnet" | "localnet" | "unknown";
+export declare function assertMintMatchesRpcCluster(input: {
+    mintAddress: string;
+    mintName: string;
+    rpcUrl: string;
+}): void;
+export declare function redactSecretForLogs(): string;

package/dist/config/env.js

@@ -8,6 +8,12 @@ exports.getOptionalSecretKey = getOptionalSecretKey;
 exports.getOptionalDevnetTreasurySecretKey = getOptionalDevnetTreasurySecretKey;
 exports.getRpcUrl = getRpcUrl;
 exports.getRpcFallbackUrl = getRpcFallbackUrl;
+exports.getZkCompressionApiUrl = getZkCompressionApiUrl;
+exports.getZkProverUrl = getZkProverUrl;
+exports.getOnchainPolicyGuardProgramId = getOnchainPolicyGuardProgramId;
+exports.getImplementationPath = getImplementationPath;
+exports.isDefensibleDevnetDemoMode = isDefensibleDevnetDemoMode;
+exports.isNeonBroadcastEnabled = isNeonBroadcastEnabled;
 exports.getKoraRpcUrl = getKoraRpcUrl;
 exports.isKoraMockMode = isKoraMockMode;
 exports.getJupiterApiBaseUrl = getJupiterApiBaseUrl;
@@ -48,6 +54,11 @@ 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 ZK_COMPRESSION_API_URL_ENV = "ZK_COMPRESSION_API_URL";
+const ZK_PROVER_URL_ENV = "ZK_PROVER_URL";
+const ONCHAIN_POLICY_GUARD_PROGRAM_ID_ENV = "ONCHAIN_POLICY_GUARD_PROGRAM_ID";
+const IMPLEMENTATION_PATH_ENV = "IMPLEMENTATION_PATH";
+const NEON_BROADCAST_ENABLED_ENV = "NEON_BROADCAST_ENABLED";
 const MAINNET_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
 const DEVNET_USDC_MINT = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
 class EnvConfigError extends Error {
@@ -102,6 +113,32 @@ function getRpcFallbackUrl() {
     const fallbackUrl = process.env[RPC_FALLBACK_ENV]?.trim();
     return fallbackUrl && fallbackUrl.length > 0 ? fallbackUrl : null;
 }
+function getZkCompressionApiUrl() {
+    const value = process.env[ZK_COMPRESSION_API_URL_ENV]?.trim();
+    return value && value.length > 0 ? value : null;
+}
+function getZkProverUrl() {
+    const value = process.env[ZK_PROVER_URL_ENV]?.trim();
+    return value && value.length > 0 ? value : null;
+}
+function getOnchainPolicyGuardProgramId() {
+    const value = process.env[ONCHAIN_POLICY_GUARD_PROGRAM_ID_ENV]?.trim();
+    return value && value.length > 0 ? value : null;
+}
+function getImplementationPath() {
+    const value = process.env[IMPLEMENTATION_PATH_ENV]?.trim();
+    return value && value.length > 0 ? value : "strict_live";
+}
+function isDefensibleDevnetDemoMode() {
+    return getImplementationPath() === "defensible_devnet_demo";
+}
+function isNeonBroadcastEnabled() {
+    const rawValue = process.env[NEON_BROADCAST_ENABLED_ENV]?.trim().toLowerCase();
+    if (!rawValue) {
+        return false;
+    }
+    return rawValue === "true" || rawValue === "1";
+}
 function getKoraRpcUrl() {
     const koraRpcUrl = process.env[KORA_RPC_ENV]?.trim();
     return koraRpcUrl && koraRpcUrl.length > 0

package/dist/config/policyPresets.d.ts

@@ -0,0 +1,22 @@
+import type { PolicyConfig } from "../policy";
+import type { PolicyPresetName, StoredPolicyOverrides } from "../cli/types";
+type PolicyPresetDefinition = {
+    description: string;
+    label: string;
+    build: (input: {
+        agentId: string;
+    }) => PolicyConfig;
+};
+export declare const POLICY_PRESETS: Record<PolicyPresetName, PolicyPresetDefinition>;
+export declare const DEFAULT_POLICY_PRESET: PolicyPresetName;
+export declare function listPolicyPresetSummaries(): Array<{
+    description: string;
+    label: string;
+    name: PolicyPresetName;
+}>;
+export declare function resolvePolicyConfig(input: {
+    agentId: string;
+    overrides?: StoredPolicyOverrides;
+    presetName: PolicyPresetName;
+}): PolicyConfig;
+export {};

package/dist/core/balances/BalanceService.d.ts

@@ -0,0 +1,14 @@
+import { PublicKey } from "@solana/web3.js";
+import { RpcClient } from "../rpc/RpcClient";
+import { TokenService } from "../tokens/TokenService";
+export declare class BalanceService {
+    private readonly rpcClient;
+    private readonly tokenService;
+    constructor(rpcClient: RpcClient, tokenService: TokenService);
+    getSolBalanceLamports(owner: PublicKey): Promise<number>;
+    getSolBalance(owner: PublicKey): Promise<number>;
+    getSplTokenBalance(input: {
+        owner: PublicKey;
+        mint: PublicKey;
+    }): Promise<number>;
+}

package/dist/core/funding/DevnetFundingService.d.ts

@@ -0,0 +1,38 @@
+import { type PublicKey } from "@solana/web3.js";
+import { BalanceService } from "../balances/BalanceService";
+import { RpcClient } from "../rpc/RpcClient";
+import { TransactionService } from "../transactions/TransactionService";
+import { WalletManager } from "../wallet/WalletManager";
+type FundingResult = {
+    signature: string;
+    source: "airdrop" | "hybrid" | "treasury-transfer";
+};
+export declare class DevnetFundingService {
+    private readonly rpcClient;
+    private readonly transactionService;
+    private readonly treasuryWallet;
+    constructor(rpcClient: RpcClient, transactionService: TransactionService, treasuryWallet?: WalletManager | null);
+    hasTreasuryWallet(): boolean;
+    getTreasuryPublicKey(): PublicKey | null;
+    ensureMinimumSol(input: {
+        airdropAmountSol?: number;
+        balanceService: BalanceService;
+        minimumSol: number;
+        recipient: PublicKey;
+    }): Promise<FundingResult | null>;
+    fundExactSol(input: {
+        amountSol: number;
+        recipient: PublicKey;
+    }): Promise<FundingResult>;
+    waitForMinimumBalance(input: {
+        attempts?: number;
+        balanceService: BalanceService;
+        minimumSol: number;
+        recipient: PublicKey;
+    }): Promise<number>;
+    private canUseTreasury;
+    private fundFromTreasury;
+    private fundFromTreasuryOrAirdrop;
+    private requestAirdrop;
+}
+export {};

package/dist/core/funding/DevnetFundingService.js

@@ -4,6 +4,7 @@ exports.DevnetFundingService = void 0;
 const web3_js_1 = require("@solana/web3.js");
 const env_1 = require("../../config/env");
 const WalletManager_1 = require("../wallet/WalletManager");
+const TREASURY_MINIMUM_REMAINING_LAMPORTS = Math.round(0.05 * web3_js_1.LAMPORTS_PER_SOL);
 class DevnetFundingService {
     rpcClient;
     transactionService;
@@ -26,19 +27,24 @@ class DevnetFundingService {
         }
         const amountSol = roundSolAmount(input.minimumSol - currentBalance);
         if (this.canUseTreasury(input.recipient)) {
-            return this.fundFromTreasury({
+            return this.fundFromTreasuryOrAirdrop({
+                airdropAmountSol: input.airdropAmountSol ?? amountSol,
                 amountSol,
                 recipient: input.recipient
             });
         }
         return this.requestAirdrop({
-            amountSol: input.airdropAmountSol ?? Math.max(amountSol, 1),
+            amountSol: input.airdropAmountSol ?? amountSol,
             recipient: input.recipient
         });
     }
     async fundExactSol(input) {
         if (this.canUseTreasury(input.recipient)) {
-            return this.fundFromTreasury(input);
+            return this.fundFromTreasuryOrAirdrop({
+                airdropAmountSol: input.amountSol,
+                amountSol: input.amountSol,
+                recipient: input.recipient
+            });
         }
         return this.requestAirdrop(input);
     }
@@ -78,11 +84,72 @@ class DevnetFundingService {
             source: "treasury-transfer"
         };
     }
+    async fundFromTreasuryOrAirdrop(input) {
+        try {
+            const treasuryLamports = await this.rpcClient.getBalance(this.treasuryWallet.publicKey, "confirmed");
+            const requestedLamports = Math.round(input.amountSol * web3_js_1.LAMPORTS_PER_SOL);
+            const transferableLamports = Math.max(0, treasuryLamports - TREASURY_MINIMUM_REMAINING_LAMPORTS);
+            if (transferableLamports >= requestedLamports) {
+                return await this.fundFromTreasury({
+                    amountSol: input.amountSol,
+                    recipient: input.recipient
+                });
+            }
+            if (transferableLamports > 0) {
+                await this.fundFromTreasury({
+                    amountSol: transferableLamports / web3_js_1.LAMPORTS_PER_SOL,
+                    recipient: input.recipient
+                });
+                const remainingLamports = requestedLamports - transferableLamports;
+                const airdropFunding = await this.requestAirdrop({
+                    amountSol: remainingLamports / web3_js_1.LAMPORTS_PER_SOL,
+                    recipient: input.recipient
+                });
+                return {
+                    signature: airdropFunding.signature,
+                    source: "hybrid"
+                };
+            }
+        }
+        catch {
+            // Fall through to full-faucet funding below.
+        }
+        return this.requestAirdrop({
+            amountSol: input.airdropAmountSol,
+            recipient: input.recipient
+        });
+    }
     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");
+        let remainingLamports = Math.round(input.amountSol * web3_js_1.LAMPORTS_PER_SOL);
+        let lastSignature = "";
+        let lastError;
+        while (remainingLamports > 0) {
+            const requestLamports = Math.min(remainingLamports, web3_js_1.LAMPORTS_PER_SOL);
+            let requestSucceeded = false;
+            for (let attempt = 0; attempt < 5; attempt += 1) {
+                try {
+                    lastSignature = await this.rpcClient.requestAirdrop(input.recipient, requestLamports);
+                    await this.rpcClient.confirmTransaction(lastSignature, "confirmed");
+                    remainingLamports -= requestLamports;
+                    lastError = undefined;
+                    requestSucceeded = true;
+                    break;
+                }
+                catch (error) {
+                    lastError = error;
+                    await delay(1_500);
+                }
+            }
+            if (!requestSucceeded) {
+                break;
+            }
+        }
+        if (!lastSignature || remainingLamports > 0) {
+            const reason = lastError instanceof Error ? lastError.message : "unknown error";
+            throw new Error(`airdrop to ${input.recipient.toBase58()} failed: ${reason}`);
+        }
         return {
-            signature,
+            signature: lastSignature,
             source: "airdrop"
         };
     }

package/dist/core/idempotency/ExecutionIdempotencyGuard.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Prevents duplicate execution of the same intent by tracking unique execution IDs.
+ * Uses a bounded in-memory set with TTL-based expiry.
+ */
+export declare class ExecutionIdempotencyGuard {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly ttlMs;
+    private cleanupCounter;
+    private readonly cleanupInterval;
+    constructor(options?: {
+        maxEntries?: number;
+        ttlMs?: number;
+    });
+    /**
+     * Generate a new unique execution ID.
+     */
+    generateId(): string;
+    /**
+     * 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: string): boolean;
+    /**
+     * Check whether an execution ID has already been acquired (without acquiring it).
+     */
+    has(executionId: string): boolean;
+    /**
+     * Returns the number of active (non-expired) tracked entries.
+     */
+    get size(): number;
+    /**
+     * Remove all tracked entries.
+     */
+    clear(): void;
+    private maybeCleanup;
+    private evictOldest;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,8 @@
+export { RpcClient } from "./rpc/RpcClient";
+export { RpcFailoverClient } from "./rpc/RpcFailoverClient";
+export { WalletManager } from "./wallet/WalletManager";
+export { TransactionService } from "./transactions/TransactionService";
+export { PostTransactionVerifier } from "./transactions/PostTransactionVerifier";
+export { TokenService } from "./tokens/TokenService";
+export { BalanceService } from "./balances/BalanceService";
+export { ExecutionIdempotencyGuard } from "./idempotency/ExecutionIdempotencyGuard";

package/dist/core/rpc/RpcClient.d.ts

@@ -0,0 +1,21 @@
+import { Connection, type Commitment, type ConfirmOptions, type PublicKey, type RpcResponseAndContext, type SignatureResult, type SimulatedTransactionResponse, type TransactionConfirmationStrategy, type VersionedTransaction } from "@solana/web3.js";
+export declare class RpcClient {
+    readonly connection: Connection;
+    private readonly failoverClient;
+    constructor(rpcUrl?: string, commitment?: Commitment);
+    get rpcUrl(): string;
+    getLatestBlockhash(commitment?: Commitment): Promise<{
+        blockhash: string;
+        lastValidBlockHeight: number;
+    }>;
+    getBalance(publicKey: PublicKey, commitment?: Commitment): Promise<number>;
+    getTokenAccountBalance(publicKey: PublicKey, commitment?: Commitment): Promise<RpcResponseAndContext<import("@solana/web3.js").TokenAmount>>;
+    getAccountInfo(publicKey: PublicKey, commitment?: Commitment): Promise<import("@solana/web3.js").AccountInfo<Buffer<ArrayBufferLike>> | null>;
+    sendTransaction(transaction: VersionedTransaction, options?: ConfirmOptions): Promise<string>;
+    confirmTransaction(strategy: TransactionConfirmationStrategy | string, commitment?: Commitment): Promise<RpcResponseAndContext<SignatureResult>>;
+    simulateTransaction(transaction: VersionedTransaction, options?: {
+        commitment?: Commitment;
+        sigVerify?: boolean;
+    }): Promise<RpcResponseAndContext<SimulatedTransactionResponse>>;
+    requestAirdrop(publicKey: PublicKey, lamports: number): Promise<string>;
+}