@prktsol/prkt 1.0.0

package/dist/agent/DecisionEngine.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecisionEngine = void 0;
+const policyFactory_1 = require("./policyFactory");
+const PolicyGuard_1 = require("../policy/PolicyGuard");
+const programs_1 = require("../solana/programs");
+const TokenWallet_1 = require("../spl/TokenWallet");
+const MINIMUM_WSOL_FOR_TRADING = 0.01;
+const MINIMUM_SOL_RESERVE = 0.1;
+const WRAP_SOL_AMOUNT = 0.05;
+const LAMPORTS_PER_SOL = 1_000_000_000;
+const ANSI_CYAN = "\u001b[36m";
+const ANSI_RESET = "\u001b[0m";
+class DecisionEngine {
+    connection;
+    walletManager;
+    logger;
+    constructor(connection, walletManager, logger = console.log) {
+        this.connection = connection;
+        this.walletManager = walletManager;
+        this.logger = logger;
+    }
+    async think() {
+        const associatedTokenAddress = TokenWallet_1.TokenWallet.findAssociatedTokenAddress(this.walletManager.publicKey, programs_1.NATIVE_MINT);
+        const existingTokenAccount = await this.connection.getAccountInfo(associatedTokenAddress, "confirmed");
+        const solBalanceLamports = await this.connection.getBalance(this.walletManager.publicKey, "confirmed");
+        const wsolBalance = await this.getWsolBalance(associatedTokenAddress, existingTokenAccount !== null);
+        const solBalance = solBalanceLamports / LAMPORTS_PER_SOL;
+        this.logger(`SOL balance: ${solBalance.toFixed(4)} SOL`);
+        this.logger(`wSOL balance: ${wsolBalance.toFixed(4)} wSOL`);
+        if (wsolBalance < MINIMUM_WSOL_FOR_TRADING && solBalance > MINIMUM_SOL_RESERVE) {
+            const reason = "Reasoning: My wSOL liquidity is low for trading. I am initiating a 0.05 SOL wrap to maintain operational readiness.";
+            this.logger(colorizeReasoning(reason));
+            const latestBlockhash = await this.connection.getLatestBlockhash("confirmed");
+            const wrapLamports = Math.round(WRAP_SOL_AMOUNT * LAMPORTS_PER_SOL);
+            const wrapSol = await TokenWallet_1.TokenWallet.buildWrapSolTransaction({
+                amountLamports: wrapLamports,
+                createAssociatedTokenAccount: existingTokenAccount === null,
+                recentBlockhash: latestBlockhash.blockhash,
+                walletManager: this.walletManager
+            });
+            const policyGuard = new PolicyGuard_1.PolicyGuard((0, policyFactory_1.createDefaultAgentPolicy)({
+                maxSpend: {
+                    lamports: wrapLamports + 1_000_000
+                },
+                whitelistedTransferDestinations: [wrapSol.associatedTokenAddress.toBase58()]
+            }));
+            policyGuard.validate(wrapSol.transaction);
+            const signature = await this.connection.sendTransaction(wrapSol.transaction, {
+                maxRetries: 3,
+                preflightCommitment: "confirmed"
+            });
+            await this.connection.confirmTransaction({
+                blockhash: latestBlockhash.blockhash,
+                lastValidBlockHeight: latestBlockhash.lastValidBlockHeight,
+                signature
+            }, "confirmed");
+            const updatedWsolBalance = await this.getWsolBalance(wrapSol.associatedTokenAddress, true);
+            return {
+                action: "wrap",
+                associatedTokenAddress: wrapSol.associatedTokenAddress.toBase58(),
+                createdAssociatedTokenAccount: wrapSol.createdAssociatedTokenAccount,
+                reason,
+                signature,
+                solBalance,
+                wrapAmount: WRAP_SOL_AMOUNT,
+                wsolBalance: updatedWsolBalance
+            };
+        }
+        const reason = "Reasoning: My current SOL and wSOL balances are sufficient. No liquidity adjustment is required.";
+        this.logger(colorizeReasoning(reason));
+        return {
+            action: "hold",
+            associatedTokenAddress: associatedTokenAddress.toBase58(),
+            reason,
+            solBalance,
+            wsolBalance
+        };
+    }
+    async getWsolBalance(associatedTokenAddress, tokenAccountExists) {
+        if (!tokenAccountExists) {
+            return 0;
+        }
+        const tokenBalance = await this.connection.getTokenAccountBalance(associatedTokenAddress, "confirmed");
+        const uiAmount = tokenBalance.value.uiAmount;
+        if (uiAmount !== null && uiAmount !== undefined) {
+            return uiAmount;
+        }
+        return Number(tokenBalance.value.amount) / LAMPORTS_PER_SOL;
+    }
+}
+exports.DecisionEngine = DecisionEngine;
+function colorizeReasoning(message) {
+    return `${ANSI_CYAN}${message}${ANSI_RESET}`;
+}

package/dist/agent/MockPriceFeed.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockPriceFeed = void 0;
+class MockPriceFeed {
+    snapshot;
+    constructor(snapshot) {
+        this.snapshot = snapshot;
+    }
+    read() {
+        return this.snapshot;
+    }
+}
+exports.MockPriceFeed = MockPriceFeed;

package/dist/agent/intents/types.js

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

package/dist/agent/new-index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UniversalDeFiStrategy = exports.TreasuryDistributorStrategy = exports.TokenRebalancerStrategy = exports.SimpleScriptedTransferStrategy = exports.MemoHeartbeatStrategy = exports.AgentRegistry = exports.AgentRunner = void 0;
+var AgentRunner_1 = require("./runner/AgentRunner");
+Object.defineProperty(exports, "AgentRunner", { enumerable: true, get: function () { return AgentRunner_1.AgentRunner; } });
+var AgentRegistry_1 = require("./registry/AgentRegistry");
+Object.defineProperty(exports, "AgentRegistry", { enumerable: true, get: function () { return AgentRegistry_1.AgentRegistry; } });
+var MemoHeartbeatStrategy_1 = require("./strategies/MemoHeartbeatStrategy");
+Object.defineProperty(exports, "MemoHeartbeatStrategy", { enumerable: true, get: function () { return MemoHeartbeatStrategy_1.MemoHeartbeatStrategy; } });
+var SimpleScriptedTransferStrategy_1 = require("./strategies/SimpleScriptedTransferStrategy");
+Object.defineProperty(exports, "SimpleScriptedTransferStrategy", { enumerable: true, get: function () { return SimpleScriptedTransferStrategy_1.SimpleScriptedTransferStrategy; } });
+var TokenRebalancerStrategy_1 = require("./strategies/TokenRebalancerStrategy");
+Object.defineProperty(exports, "TokenRebalancerStrategy", { enumerable: true, get: function () { return TokenRebalancerStrategy_1.TokenRebalancerStrategy; } });
+var TreasuryDistributorStrategy_1 = require("./strategies/TreasuryDistributorStrategy");
+Object.defineProperty(exports, "TreasuryDistributorStrategy", { enumerable: true, get: function () { return TreasuryDistributorStrategy_1.TreasuryDistributorStrategy; } });
+var UniversalDeFiStrategy_1 = require("./strategies/UniversalDeFiStrategy");
+Object.defineProperty(exports, "UniversalDeFiStrategy", { enumerable: true, get: function () { return UniversalDeFiStrategy_1.UniversalDeFiStrategy; } });

package/dist/agent/policyFactory.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultAgentPolicy = createDefaultAgentPolicy;
+const web3_js_1 = require("@solana/web3.js");
+const env_1 = require("../config/env");
+const programs_1 = require("../solana/programs");
+function createDefaultAgentPolicy(overrides) {
+    const sessionTtlMinutes = (0, env_1.getPolicySessionTtlMinutes)();
+    const sessionExpiryIso = new Date(Date.now() + sessionTtlMinutes * 60_000).toISOString();
+    return {
+        protocolPolicies: {
+            kamino: {
+                allowedMarkets: ["main-usdc-vault"],
+                enabled: true,
+                maxExposureLamports: 1_000_000_000,
+                maxSlippageBps: 75,
+                minHealthFactor: 1.5
+            },
+            jupiter: {
+                allowedMarkets: ["sol-usdc"],
+                enabled: true,
+                maxExposureLamports: 1_000_000_000,
+                maxSlippageBps: 100
+            },
+            marinade: {
+                allowedMarkets: ["primary-stake-pool"],
+                enabled: true,
+                maxExposureLamports: 1_000_000_000,
+                maxSlippageBps: 50
+            },
+            raydium: {
+                allowedMarkets: ["sol-usdc-core-pool"],
+                enabled: true,
+                maxExposureLamports: 1_000_000_000,
+                maxSlippageBps: 100
+            }
+        },
+        maxSpend: {
+            lamports: 1_000_000
+        },
+        whitelistedPrograms: [
+            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(),
+            ...(0, env_1.getExtraWhitelistedPrograms)()
+        ],
+        sessionExpiry: {
+            iso8601: sessionExpiryIso
+        },
+        whitelistedTransferDestinations: [],
+        ...overrides
+    };
+}

package/dist/agent/registry/AgentRegistry.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRegistry = void 0;
+class AgentRegistry {
+    agents = new Map();
+    register(agent) {
+        this.agents.set(agent.context.id, agent);
+    }
+    get(agentId) {
+        return this.agents.get(agentId);
+    }
+    list() {
+        return Array.from(this.agents.values());
+    }
+}
+exports.AgentRegistry = AgentRegistry;

package/dist/agent/runner/AgentRunner.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRunner = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const policy_1 = require("../../policy");
+const AgentRegistry_1 = require("../registry/AgentRegistry");
+class AgentRunner {
+    registry = new AgentRegistry_1.AgentRegistry();
+    runtimes = new Map();
+    registerAgent(input) {
+        const policyConfig = input.policyConfig ?? input.context.policyConfig;
+        const policyEngine = new policy_1.PolicyEngine({
+            ...policyConfig,
+            approvalMode: input.approvalMode ?? policyConfig.approvalMode
+        });
+        const sandboxExecutor = new policy_1.SandboxExecutor(policyEngine, input.context.transactionService, input.approvalMode ?? policyConfig.approvalMode, input.approvalCallback);
+        this.registry.register({
+            context: {
+                ...input.context,
+                policyConfig
+            },
+            strategy: input.strategy
+        });
+        this.runtimes.set(input.context.id, {
+            context: {
+                ...input.context,
+                policyConfig
+            },
+            approvalCallback: input.approvalCallback,
+            approvalMode: input.approvalMode ?? policyConfig.approvalMode,
+            strategy: input.strategy,
+            policyEngine,
+            sandboxExecutor
+        });
+    }
+    listAgents() {
+        return this.registry.list().map((entry) => ({
+            id: entry.context.id,
+            strategy: entry.strategy.name
+        }));
+    }
+    async runOnceParallel() {
+        const agents = this.registry.list();
+        return Promise.all(agents.map(async (registered) => {
+            const runtime = this.runtimes.get(registered.context.id);
+            if (!runtime) {
+                return {
+                    agentId: registered.context.id,
+                    strategy: registered.strategy.name,
+                    outcomes: []
+                };
+            }
+            const intents = await registered.strategy.nextIntents(registered.context);
+            const outcomes = await this.executeIntents(runtime, intents);
+            return {
+                agentId: registered.context.id,
+                strategy: registered.strategy.name,
+                outcomes
+            };
+        }));
+    }
+    async runRounds(rounds) {
+        const aggregate = new Map();
+        for (let index = 0; index < rounds; index += 1) {
+            const results = await this.runOnceParallel();
+            for (const result of results) {
+                const existing = aggregate.get(result.agentId);
+                if (!existing) {
+                    aggregate.set(result.agentId, {
+                        ...result,
+                        outcomes: [...result.outcomes]
+                    });
+                    continue;
+                }
+                existing.outcomes.push(...result.outcomes);
+            }
+        }
+        return Array.from(aggregate.values());
+    }
+    async executeIntents(runtime, intents) {
+        const outcomes = [];
+        for (const intent of intents) {
+            try {
+                if (intent.type === "defi-capability") {
+                    if (!runtime.context.universalDeFiExecutor) {
+                        throw new Error("universal DeFi executor is not configured for this agent");
+                    }
+                    const result = await runtime.context.universalDeFiExecutor.execute({
+                        capability: intent.capability,
+                        protocol: intent.protocol,
+                        snapshot: intent.snapshot
+                    }, {
+                        liveExecutor: {
+                            executePreparedTransaction: (input) => this.executePreparedTransaction(runtime, input)
+                        }
+                    });
+                    outcomes.push({
+                        intent,
+                        allowed: result.result !== null,
+                        signature: result.result?.signature ?? null,
+                        reasons: result.result
+                            ? result.result.mock
+                                ? ["executed via memo/mock fallback"]
+                                : []
+                            : [`no execution for ${result.capability}/${result.protocol}`]
+                    });
+                    continue;
+                }
+                const built = await this.buildIntentTransaction(runtime.context, intent);
+                const execution = await runtime.sandboxExecutor.executePreparedTransaction({
+                    confirmationStrategy: built.confirmationStrategy,
+                    transaction: built.transaction
+                });
+                const allowed = execution.signature !== null;
+                outcomes.push({
+                    intent,
+                    allowed,
+                    signature: execution.signature,
+                    reasons: execution.inspection.reasons
+                });
+            }
+            catch (error) {
+                outcomes.push({
+                    intent,
+                    allowed: false,
+                    signature: null,
+                    reasons: [error instanceof Error ? error.message : "unknown intent failure"]
+                });
+            }
+        }
+        return outcomes;
+    }
+    async buildIntentTransaction(context, intent) {
+        if (intent.type === "write-memo") {
+            return context.transactionService.buildTransaction({
+                feePayer: context.walletPublicKey,
+                instructions: [context.transactionService.buildMemoInstruction(intent.memo)],
+                signer: context.walletManager
+            });
+        }
+        if (intent.type === "transfer-sol") {
+            return context.transactionService.buildTransaction({
+                feePayer: context.walletPublicKey,
+                instructions: [
+                    context.transactionService.buildSolTransferInstruction({
+                        from: context.walletPublicKey,
+                        to: new web3_js_1.PublicKey(intent.to),
+                        lamports: intent.lamports
+                    })
+                ],
+                signer: context.walletManager
+            });
+        }
+        if (intent.type === "create-ata") {
+            const ata = await context.tokenService.ensureAtaInstruction({
+                mint: new web3_js_1.PublicKey(intent.mint),
+                owner: new web3_js_1.PublicKey(intent.owner),
+                payer: context.walletPublicKey
+            });
+            if (!ata.createInstruction) {
+                return context.transactionService.buildTransaction({
+                    feePayer: context.walletPublicKey,
+                    instructions: [context.transactionService.buildMemoInstruction(`ata-exists:${ata.address.toBase58()}`)],
+                    signer: context.walletManager
+                });
+            }
+            return context.transactionService.buildTransaction({
+                feePayer: context.walletPublicKey,
+                instructions: [ata.createInstruction],
+                signer: context.walletManager
+            });
+        }
+        if (intent.type === "transfer-spl") {
+            const mint = new web3_js_1.PublicKey(intent.mint);
+            const mintDecimals = await context.tokenService.getMintDecimals(mint);
+            const sourceAta = context.tokenService.findAssociatedTokenAddress(context.walletPublicKey, mint);
+            const destinationAta = context.tokenService.findAssociatedTokenAddress(new web3_js_1.PublicKey(intent.toOwner), mint);
+            const createDestination = await context.tokenService.ensureAtaInstruction({
+                mint,
+                owner: new web3_js_1.PublicKey(intent.toOwner),
+                payer: context.walletPublicKey
+            });
+            const instructions = [
+                ...(createDestination.createInstruction ? [createDestination.createInstruction] : []),
+                context.transactionService.buildSplTransferCheckedInstruction({
+                    sourceAta,
+                    mint,
+                    destinationAta,
+                    owner: context.walletPublicKey,
+                    amount: intent.amountRaw,
+                    decimals: mintDecimals
+                })
+            ];
+            return context.transactionService.buildTransaction({
+                feePayer: context.walletPublicKey,
+                instructions,
+                signer: context.walletManager
+            });
+        }
+        if (intent.type === "mint-token") {
+            const mint = new web3_js_1.PublicKey(intent.mint);
+            const destinationOwner = new web3_js_1.PublicKey(intent.toOwner);
+            const destination = await context.tokenService.ensureAtaInstruction({
+                mint,
+                owner: destinationOwner,
+                payer: context.walletPublicKey
+            });
+            const instructions = [
+                ...(destination.createInstruction ? [destination.createInstruction] : []),
+                context.tokenService.buildMintToInstruction({
+                    mint,
+                    destinationAta: destination.address,
+                    authority: context.walletPublicKey,
+                    amount: intent.amountRaw
+                })
+            ];
+            return context.transactionService.buildTransaction({
+                feePayer: context.walletPublicKey,
+                instructions,
+                signer: context.walletManager
+            });
+        }
+        throw new Error(`Unsupported intent type: ${intent.type}`);
+    }
+    executePreparedTransaction(runtime, input) {
+        const sandboxExecutor = input.policyConfigPatch
+            ? this.createSandboxExecutor(runtime, input.policyConfigPatch)
+            : runtime.sandboxExecutor;
+        return sandboxExecutor.executePreparedTransaction({
+            confirmationStrategy: input.confirmationStrategy,
+            inspectionContext: input.inspectionContext,
+            transaction: input.transaction
+        });
+    }
+    createSandboxExecutor(runtime, patch) {
+        const merged = this.mergePolicyConfig(runtime.context.policyConfig, patch);
+        const policyEngine = new policy_1.PolicyEngine({
+            ...merged,
+            approvalMode: runtime.approvalMode
+        });
+        return new policy_1.SandboxExecutor(policyEngine, runtime.context.transactionService, runtime.approvalMode, runtime.approvalCallback);
+    }
+    mergePolicyConfig(base, patch) {
+        return {
+            ...base,
+            limits: {
+                ...base.limits,
+                ...patch.limits
+            },
+            rules: {
+                ...base.rules,
+                ...patch.rules,
+                allowedMintAddresses: this.mergeUnique(base.rules.allowedMintAddresses, patch.rules?.allowedMintAddresses),
+                allowedProgramIds: this.mergeUnique(base.rules.allowedProgramIds, patch.rules?.allowedProgramIds),
+                allowOpaqueProgramIds: this.mergeUnique(base.rules.allowOpaqueProgramIds ?? [], patch.rules?.allowOpaqueProgramIds),
+                allowedCloseAccountDestinations: this.mergeUnique(base.rules.allowedCloseAccountDestinations ?? [], patch.rules?.allowedCloseAccountDestinations),
+                allowedTransferDestinations: this.mergeUnique(base.rules.allowedTransferDestinations ?? [], patch.rules?.allowedTransferDestinations)
+            },
+            sessionExpiresAtIso8601: patch.sessionExpiresAtIso8601 ?? base.sessionExpiresAtIso8601
+        };
+    }
+    mergeUnique(base, extra) {
+        return Array.from(new Set([...base, ...(extra ?? [])]));
+    }
+}
+exports.AgentRunner = AgentRunner;

package/dist/agent/strategies/MemoHeartbeatStrategy.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoHeartbeatStrategy = void 0;
+class MemoHeartbeatStrategy {
+    name = "memo-heartbeat";
+    async nextIntents(context) {
+        return [
+            {
+                type: "write-memo",
+                memo: `heartbeat:${context.id}:${new Date().toISOString()}`
+            }
+        ];
+    }
+}
+exports.MemoHeartbeatStrategy = MemoHeartbeatStrategy;

package/dist/agent/strategies/SimpleScriptedTransferStrategy.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleScriptedTransferStrategy = void 0;
+class SimpleScriptedTransferStrategy {
+    plan;
+    name = "simple-scripted-transfer";
+    constructor(plan) {
+        this.plan = plan;
+    }
+    async nextIntents(_context) {
+        const intents = [
+            {
+                type: "transfer-sol",
+                to: this.plan.to,
+                lamports: this.plan.lamports
+            }
+        ];
+        if (this.plan.memo) {
+            intents.push({
+                type: "write-memo",
+                memo: this.plan.memo
+            });
+        }
+        return intents;
+    }
+}
+exports.SimpleScriptedTransferStrategy = SimpleScriptedTransferStrategy;

package/dist/agent/strategies/TokenRebalancerStrategy.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenRebalancerStrategy = void 0;
+const web3_js_1 = require("@solana/web3.js");
+class TokenRebalancerStrategy {
+    config;
+    name = "token-rebalancer";
+    constructor(config) {
+        this.config = config;
+    }
+    async nextIntents(context) {
+        const mint = new web3_js_1.PublicKey(this.config.mint);
+        const currentBalance = await context.balanceService.getSplTokenBalance({
+            owner: context.walletPublicKey,
+            mint
+        });
+        if (currentBalance >= this.config.minBalanceUi) {
+            return [];
+        }
+        return [
+            {
+                type: "create-ata",
+                mint: this.config.mint,
+                owner: this.config.targetOwner
+            },
+            {
+                type: "transfer-spl",
+                mint: this.config.mint,
+                toOwner: this.config.targetOwner,
+                amountRaw: this.config.topUpRawAmount
+            }
+        ];
+    }
+}
+exports.TokenRebalancerStrategy = TokenRebalancerStrategy;

package/dist/agent/strategies/TreasuryDistributorStrategy.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TreasuryDistributorStrategy = void 0;
+class TreasuryDistributorStrategy {
+    config;
+    name = "treasury-distributor";
+    constructor(config) {
+        this.config = config;
+    }
+    async nextIntents(_context) {
+        return this.config.recipients.flatMap((recipient) => {
+            const intents = [
+                {
+                    type: "create-ata",
+                    mint: this.config.mint,
+                    owner: recipient
+                },
+                {
+                    type: "transfer-spl",
+                    mint: this.config.mint,
+                    toOwner: recipient,
+                    amountRaw: this.config.amountRawPerRecipient
+                }
+            ];
+            return intents;
+        });
+    }
+}
+exports.TreasuryDistributorStrategy = TreasuryDistributorStrategy;

package/dist/agent/strategies/UniversalDeFiStrategy.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UniversalDeFiStrategy = void 0;
+class UniversalDeFiStrategy {
+    requests;
+    name = "universal-defi";
+    constructor(requests) {
+        this.requests = requests;
+    }
+    async nextIntents(_context) {
+        return this.requests.map((request) => ({
+            type: "defi-capability",
+            capability: request.capability,
+            protocol: request.protocol,
+            snapshot: request.snapshot
+        }));
+    }
+}
+exports.UniversalDeFiStrategy = UniversalDeFiStrategy;

package/dist/agent/types/AgentContext.js

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