@prktsol/prkt 1.0.0

package/.env.devnet.all-protocols.example

@@ -0,0 +1,18 @@
+SOLANA_RPC_URL=https://api.devnet.solana.com
+# SOLANA_RPC_FALLBACK_URL=https://devnet.helius-rpc.com/?api-key=YOUR_KEY
+KORA_RPC_URL=https://kora.devnet.lazorkit.com
+KORA_MOCK_MODE=true
+JUPITER_API_BASE_URL=https://lite-api.jup.ag
+ENABLE_LIVE_SWAP_PATH=true
+ENABLE_LIVE_RAYDIUM_LP=true
+ENABLE_LIVE_KAMINO=true
+ENABLE_LIVE_MARINADE=true
+RAYDIUM_LP_CONFIG_PATH=raydium_lp.devnet.json
+KAMINO_LIVE_CONFIG_PATH=kamino_live.json
+UNIVERSAL_DEFI_LIVE_FIRST=true
+USDC_MINT=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
+EXTRA_WHITELISTED_PROGRAMS=
+POLICY_SESSION_TTL_MINUTES=60
+# Requires both raydium_lp.devnet.json and kamino_live.json to be present and valid.
+AGENT_PRIVATE_KEY=[]
+DEVNET_TREASURY_PRIVATE_KEY=[]

package/.env.devnet.autonomous.example

@@ -0,0 +1,16 @@
+SOLANA_RPC_URL=https://api.devnet.solana.com
+# SOLANA_RPC_FALLBACK_URL=https://devnet.helius-rpc.com/?api-key=YOUR_KEY
+KORA_RPC_URL=https://kora.devnet.lazorkit.com
+KORA_MOCK_MODE=true
+JUPITER_API_BASE_URL=https://lite-api.jup.ag
+ENABLE_LIVE_SWAP_PATH=false
+ENABLE_LIVE_RAYDIUM_LP=false
+ENABLE_LIVE_KAMINO=true
+ENABLE_LIVE_MARINADE=true
+UNIVERSAL_DEFI_LIVE_FIRST=true
+USDC_MINT=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
+EXTRA_WHITELISTED_PROGRAMS=
+POLICY_SESSION_TTL_MINUTES=60
+# Autonomous bounty demo generates its own wallet. If DEVNET_TREASURY_PRIVATE_KEY is set, it funds from your treasury wallet before falling back to airdrop.
+AGENT_PRIVATE_KEY=[]
+DEVNET_TREASURY_PRIVATE_KEY=[]

package/.env.devnet.jupiter.example

@@ -0,0 +1,16 @@
+SOLANA_RPC_URL=https://api.devnet.solana.com
+# SOLANA_RPC_FALLBACK_URL=https://devnet.helius-rpc.com/?api-key=YOUR_KEY
+KORA_RPC_URL=https://kora.devnet.lazorkit.com
+KORA_MOCK_MODE=true
+JUPITER_API_BASE_URL=https://lite-api.jup.ag
+ENABLE_LIVE_SWAP_PATH=true
+ENABLE_LIVE_RAYDIUM_LP=false
+ENABLE_LIVE_KAMINO=false
+ENABLE_LIVE_MARINADE=false
+UNIVERSAL_DEFI_LIVE_FIRST=true
+USDC_MINT=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
+EXTRA_WHITELISTED_PROGRAMS=
+POLICY_SESSION_TTL_MINUTES=60
+# Jupiter devnet live path still depends on route/API availability and wallet funding.
+AGENT_PRIVATE_KEY=[]
+

package/.env.devnet.kamino.example

@@ -0,0 +1,17 @@
+SOLANA_RPC_URL=https://api.devnet.solana.com
+# SOLANA_RPC_FALLBACK_URL=https://devnet.helius-rpc.com/?api-key=YOUR_KEY
+KORA_RPC_URL=https://kora.devnet.lazorkit.com
+KORA_MOCK_MODE=true
+JUPITER_API_BASE_URL=https://lite-api.jup.ag
+ENABLE_LIVE_SWAP_PATH=false
+ENABLE_LIVE_RAYDIUM_LP=false
+ENABLE_LIVE_KAMINO=true
+ENABLE_LIVE_MARINADE=false
+KAMINO_LIVE_CONFIG_PATH=kamino_live.json
+UNIVERSAL_DEFI_LIVE_FIRST=true
+USDC_MINT=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
+EXTRA_WHITELISTED_PROGRAMS=
+POLICY_SESSION_TTL_MINUTES=60
+# Requires kamino_live.json copied from kamino_live.example.json and filled with devnet values.
+AGENT_PRIVATE_KEY=[]
+

package/.env.devnet.marinade.example

@@ -0,0 +1,16 @@
+SOLANA_RPC_URL=https://api.devnet.solana.com
+# SOLANA_RPC_FALLBACK_URL=https://devnet.helius-rpc.com/?api-key=YOUR_KEY
+KORA_RPC_URL=https://kora.devnet.lazorkit.com
+KORA_MOCK_MODE=true
+JUPITER_API_BASE_URL=https://lite-api.jup.ag
+ENABLE_LIVE_SWAP_PATH=false
+ENABLE_LIVE_RAYDIUM_LP=false
+ENABLE_LIVE_KAMINO=false
+ENABLE_LIVE_MARINADE=true
+UNIVERSAL_DEFI_LIVE_FIRST=true
+USDC_MINT=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
+EXTRA_WHITELISTED_PROGRAMS=
+POLICY_SESSION_TTL_MINUTES=60
+# Use a funded devnet wallet or switch to REMOTE_SIGNER_*.
+AGENT_PRIVATE_KEY=[]
+DEVNET_TREASURY_PRIVATE_KEY=[]

package/.env.devnet.orca.example

@@ -0,0 +1,16 @@
+SOLANA_RPC_URL=https://api.devnet.solana.com
+# SOLANA_RPC_FALLBACK_URL=https://devnet.helius-rpc.com/?api-key=YOUR_KEY
+KORA_RPC_URL=https://kora.devnet.lazorkit.com
+KORA_MOCK_MODE=true
+JUPITER_API_BASE_URL=https://lite-api.jup.ag
+ENABLE_LIVE_SWAP_PATH=false
+ENABLE_LIVE_RAYDIUM_LP=false
+ENABLE_LIVE_KAMINO=false
+ENABLE_LIVE_MARINADE=false
+UNIVERSAL_DEFI_LIVE_FIRST=true
+USDC_MINT=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
+EXTRA_WHITELISTED_PROGRAMS=
+POLICY_SESSION_TTL_MINUTES=60
+# Optional. If omitted, the Orca demo generates a fresh wallet. If DEVNET_TREASURY_PRIVATE_KEY is set, it funds from your treasury wallet before falling back to airdrop.
+AGENT_PRIVATE_KEY=[]
+DEVNET_TREASURY_PRIVATE_KEY=[]

package/.env.devnet.raydium.example

@@ -0,0 +1,17 @@
+SOLANA_RPC_URL=https://api.devnet.solana.com
+# SOLANA_RPC_FALLBACK_URL=https://devnet.helius-rpc.com/?api-key=YOUR_KEY
+KORA_RPC_URL=https://kora.devnet.lazorkit.com
+KORA_MOCK_MODE=true
+JUPITER_API_BASE_URL=https://lite-api.jup.ag
+ENABLE_LIVE_SWAP_PATH=false
+ENABLE_LIVE_RAYDIUM_LP=true
+ENABLE_LIVE_KAMINO=false
+ENABLE_LIVE_MARINADE=false
+RAYDIUM_LP_CONFIG_PATH=raydium_lp.devnet.json
+UNIVERSAL_DEFI_LIVE_FIRST=true
+USDC_MINT=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
+EXTRA_WHITELISTED_PROGRAMS=
+POLICY_SESSION_TTL_MINUTES=60
+# Requires raydium_lp.devnet.json copied from raydium_lp.devnet.example.json and filled with a real devnet pool/account set.
+AGENT_PRIVATE_KEY=[]
+

package/.env.example

@@ -0,0 +1,32 @@
+SOLANA_RPC_URL=https://api.devnet.solana.com
+# Optional fallback RPC endpoint. Used by RpcFailoverClient when the primary is unreachable.
+# SOLANA_RPC_FALLBACK_URL=https://devnet.helius-rpc.com/?api-key=YOUR_KEY
+KORA_RPC_URL=https://kora.devnet.lazorkit.com
+KORA_MOCK_MODE=true
+JUPITER_API_BASE_URL=https://lite-api.jup.ag
+ENABLE_LIVE_SWAP_PATH=false
+ENABLE_LIVE_RAYDIUM_LP=false
+ENABLE_LIVE_KAMINO=false
+# Set true for the autonomous agent wallet bounty demo and direct Marinade staking demo.
+ENABLE_LIVE_MARINADE=false
+# KAMINO_LIVE_CONFIG_PATH=kamino_live.json
+UNIVERSAL_DEFI_LIVE_FIRST=true
+# Preferred production path: remote transaction signer with bearer auth.
+# REMOTE_SIGNER_URL=https://signer.example.internal/sign
+# REMOTE_SIGNER_BEARER_TOKEN=change-me
+# REMOTE_SIGNER_PUBKEY=YourSignerPublicKeyHere
+# Devnet USDC mint (default for this repository's devnet flows).
+USDC_MINT=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
+EXTRA_WHITELISTED_PROGRAMS=
+POLICY_SESSION_TTL_MINUTES=60
+# Optional: signed emergency command controls.
+# POLICY_EMERGENCY_COMMAND_PATH=emergency_command.json
+# POLICY_EMERGENCY_ADMIN_SECRET=change-me
+# POLICY_EMERGENCY_MAX_AGE_SECONDS=600
+# JSON array of 64 integers generated by Solana keypair tooling. Devnet/demo only.
+# Not required for the autonomous devnet demo, which generates a wallet programmatically.
+# Leave unset in production when using REMOTE_SIGNER_*.
+AGENT_PRIVATE_KEY=[]
+# Optional devnet treasury/faucet wallet used to fund freshly generated agent wallets when the public faucet is flaky.
+# Set this to your funded devnet wallet if you want autonomous demos and `wallet fund` to use treasury transfers first.
+DEVNET_TREASURY_PRIVATE_KEY=[]

package/ARCHITECTURE.md

@@ -0,0 +1,159 @@
+# PRKT Architecture Deep Dive
+
+## Overview
+
+PRKT is a layered agentic wallet runtime designed for secure autonomous operation on Solana devnet.
+
+## Architecture Diagram
+
+```mermaid
+flowchart LR
+  A[Strategies] --> B[AgentRunner]
+  B --> C[Intents]
+  C --> D[PolicyEngine]
+  D --> E[SandboxExecutor]
+  E --> F[Wallet Core]
+  F --> G[Solana Devnet RPC]
+
+  B --> U[UniversalDeFiOrchestrator]
+  U --> J[Jupiter Live Executor]
+  U --> R[Raydium LP Live Executor]
+  U --> M[Fallback Executor]
+```
+
+## Layer 1: Wallet Core
+
+Path: `src/core`
+
+Responsibilities:
+
+- Wallet creation/loading (`WalletManager`)
+- RPC abstraction (`RpcClient`)
+- Build/simulate/send/confirm transactions (`TransactionService`)
+- ATA + mint helpers (`TokenService`)
+- SOL/SPL balances (`BalanceService`)
+
+Rules:
+
+- No strategy logic
+- No policy decisions
+
+## Layer 2: Policy + Sandbox
+
+Path: `src/policy`
+
+Responsibilities:
+
+- Spend limits (per tx/session/day)
+- Program and mint allowlists
+- Unknown instruction deny-default
+- Simulation-gated execution
+- Approval modes (`sandbox` and `live`)
+- Security audit trail
+
+Key components:
+
+- `PolicyEngine`
+- `SandboxExecutor`
+- `TxInspectionResult`
+
+## Layer 3: Agent Runner
+
+Path: `src/agent`
+
+Responsibilities:
+
+- Strategy loop and intent production
+- Agent context isolation (wallet/config/policy)
+- Parallel agent execution
+- No direct key handling in strategy layer
+
+Key components:
+
+- `AgentRunner`
+- `AgentRegistry`
+- Typed intents (`transfer-sol`, `transfer-spl`, `mint-token`, `write-memo`, `defi-capability`)
+- Strategies including universal DeFi capability strategy
+
+## Layer 4: Protocol Interaction
+
+Paths: `src/defi`, `src/demo`, `src/scripts`
+
+Responsibilities:
+
+- Protocol adapter model for Solana DeFi capabilities
+- Live-first execution for devnet where available
+- Safe fallback mode when live prerequisites fail
+
+Current live protocol paths:
+
+- Jupiter swap execution
+- Raydium LP add-liquidity execution
+
+## CLI Layer (Orchestration Only)
+
+Path: `src/cli`
+
+The CLI is an operational control plane that orchestrates existing layers:
+
+- Wallet commands call Wallet Core services.
+- Policy commands call PolicyEngine inspection.
+- Agent commands call AgentRunner and universal DeFi executor flow.
+- Monitor/audit commands read lightweight persistent state in `artifacts/`.
+
+The CLI does not introduce protocol or policy business logic into command handlers.
+
+## Security Model
+
+### Assumptions
+
+- Agent decision logic may be wrong or compromised.
+- Operators may misconfigure environment settings.
+
+### Controls
+
+- Isolation: each agent gets an independent context
+- Policy: hard limits + allowlists
+- Sandbox: simulation and approval gating before broadcast
+- Auditability: explicit allow/deny reasoning
+- Live-first fallback: avoid uncontrolled failures while preserving determinism
+
+### Residual Risks
+
+- Bad external protocol config (for example invalid Raydium pool accounts)
+- Operator key management issues
+- Incomplete live adapter coverage for all protocols
+- CLI wallet persistence is intended for local demo operations, not production custody
+
+## Step-by-Step Devnet Demo Flow
+
+1. Set env for devnet:
+- `SOLANA_RPC_URL=https://api.devnet.solana.com`
+- `REMOTE_SIGNER_URL=...`
+- `REMOTE_SIGNER_BEARER_TOKEN=...`
+- `REMOTE_SIGNER_PUBKEY=...`
+- `AGENT_PRIVATE_KEY=[...]` for local devnet/demo use only
+- `USDC_MINT=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`
+
+2. Enable live-first execution:
+- `UNIVERSAL_DEFI_LIVE_FIRST=true`
+- `ENABLE_LIVE_SWAP_PATH=true`
+- `KORA_MOCK_MODE=false`
+- optionally `ENABLE_LIVE_RAYDIUM_LP=true`
+
+3. For Raydium live LP, create `raydium_lp.devnet.json` from `raydium_lp.devnet.example.json`.
+
+4. Run universal capability demo:
+```bash
+npm run defi:universal
+```
+
+5. Run agent-runner universal flow:
+```bash
+npm run agent:defi:universal
+```
+
+6. Validate output:
+- live signatures for available live paths
+- explicit fallback messages where live requirements are missing
+- final per-action execution results