Phalnx

On-chain guardrails for AI agents on Solana. Your policies are enforced by Solana validators, not software promises.

The Problem

Every AI agent on Solana today operates with unrestricted wallet access. Frameworks like Solana Agent Kit give agents raw keypair signing authority with zero spending limits, asset restrictions, or kill switches. There is no way for an agent owner to say "this agent can spend up to 500 USDC/day on Jupiter swaps, nothing else."

The Solution

Phalnx wraps your agent's wallet with on-chain policy enforcement. One call gives you client-side fast deny, TEE key custody, and on-chain vault enforcement — bundled as one product.

import { wrap } from "@phalnx/kit";

// wrap() sandwiches any DeFi instruction with Phalnx security
// policies enforced by Solana validators

Security Model

Phalnx provides three layers of protection in a single integration:

1. Client-side policy checks — fast deny before transactions hit the network
2. TEE key custody — agent private keys stored in hardware enclaves (Crossmint, Turnkey, Privy)
3. On-chain vault enforcement — PDA vaults with cryptographic policy guarantees enforced by Solana validators

Key Features

• Stablecoin-only USD tracking — no oracle dependency, no feed staleness, no price manipulation risk. USDC/USDT amount = USD value
• Rolling 24h spending caps — 144-epoch circular buffer tracks stablecoin outflows. No exploitable midnight reset
• Risk-reducing actions exempt — closing positions, decreasing exposure, and removing collateral never count as spending
• On-chain slippage verification — Jupiter and Flash Trade slippage enforced by Solana validators via max_slippage_bps policy
• Token delegation — SPL approve/revoke CPI instead of escrow transfers
• Timelocked policy changes — queue updates with configurable delay to prevent rug-pulls
• Agent transfers — destination-allowlisted stablecoin transfers initiated by agents
• Kill switch — owner can freeze any vault instantly, revoking all agent permissions
• On-chain audit trail — every action emits Anchor events for full transaction history
• x402 payments — shieldedFetch() for automatic HTTP 402 payment negotiation, policy-enforced

How It Works

Phalnx uses instruction composition to avoid Solana's 4-level CPI depth limit. Instead of wrapping DeFi calls inside the program, it sandwiches them in an atomic transaction:

Transaction = [
  ValidateAndAuthorize,   // Phalnx checks policy, creates session, delegates tokens
  DeFi instruction(s),    // Jupiter swap, Flash Trade open, etc.
  FinalizeSession         // Phalnx records audit, revokes delegation
]

All instructions succeed or all revert atomically. The agent's signing key is validated, spending limits are checked, and the action is recorded — without adding CPI depth to the DeFi call.

Account Model

Account	Seeds	Purpose
AgentVault	[b"vault", owner, vault_id]	Multi-agent vault: up to 10 agents with per-agent permission bitmasks
PolicyConfig	[b"policy", vault]	Spending caps, protocol allowlist, leverage/slippage limits, timelock
SpendTracker	[b"tracker", vault]	Zero-copy 144-epoch circular buffer for rolling 24h USD spend tracking
SessionAuthority	[b"session", vault, agent, token_mint]	Ephemeral PDA created per action, expires after 20 slots
PendingPolicyUpdate	[b"pending_policy", vault]	Queued policy change with timelock, applied after delay
EscrowDeposit	[b"escrow", source_vault, dest_vault, escrow_id]	Cross-vault stablecoin escrow with optional SHA-256 condition proof
InstructionConstraints	[b"constraints", vault]	Up to 16 per-program instruction constraints with 7 operators
PendingConstraintsUpdate	[b"pending_constraints", vault]	Queued constraint changes with timelock
AgentSpendOverlay	[b"agent_spend", vault, shard_index]	Per-agent rolling 24h spend tracking (10 agent slots)

On-Chain Instructions (26)

Instruction	Signer	Description
initialize_vault	Owner	Create vault, policy, tracker, and overlay PDAs
deposit_funds	Owner	Transfer SPL tokens into vault
register_agent	Owner	Register agent with permission bitmask and spending limit
update_policy	Owner	Modify policy (direct if no timelock)
update_agent_permissions	Owner	Update agent permissions and spending limit
validate_and_authorize	Agent	Check policy, collect fees, create session, delegate tokens
finalize_session	Agent	Revoke delegation, close session PDA
revoke_agent	Owner	Kill switch — freeze vault
reactivate_vault	Owner	Unfreeze vault, optionally rotate agent key
withdraw_funds	Owner	Withdraw tokens to owner
close_vault	Owner	Close all PDAs, reclaim rent
queue_policy_update	Owner	Queue timelocked policy change
apply_pending_policy	Owner	Apply queued change after timelock expires
cancel_pending_policy	Owner	Cancel queued policy change
agent_transfer	Agent	Transfer stablecoins to allowlisted destination
sync_positions	Owner	Correct open position counter if out of sync
create_escrow	Agent	Create cross-vault stablecoin escrow
settle_escrow	Agent	Settle escrow to destination vault
refund_escrow	Agent	Refund expired escrow to source vault
close_settled_escrow	Owner	Close settled/refunded escrow PDA, reclaim rent
create_instruction_constraints	Owner	Create per-program instruction constraints
close_instruction_constraints	Owner	Close instruction constraints PDA
update_instruction_constraints	Owner	Update constraints (direct if no timelock)
queue_constraints_update	Owner	Queue timelocked constraint change
apply_constraints_update	Owner	Apply queued constraint change after timelock
cancel_constraints_update	Owner	Cancel queued constraint change

Packages

Package	Description	npm
@phalnx/core	Pure TypeScript policy engine — zero blockchain dependencies
@phalnx/kit	Kit-native SDK — wrap() API, TEE custody, protocol-agnostic
@phalnx/platform	Platform client — request TEE wallet provisioning via Solana Actions
@phalnx/custody-crossmint	Crossmint TEE custody adapter — hardware-enclave signing

Quick Start

Option A — Add to an Existing Project

npm install @phalnx/kit

import { wrap } from "@phalnx/kit";

// wrap() sandwiches any DeFi instruction with Phalnx security
// policies enforced by Solana validators

Program

Network	Program ID
Devnet	4ZeVCqnjUgUtFrHHPG7jELUxvJeoVGHhGNgPrhBPwrHL

Development

# Build the Anchor program (--no-idl required on stable Rust with Anchor 0.32.1)
anchor build --no-idl

# Generate IDL separately (requires nightly Rust — anchor-syn 0.32.1 bug)
RUSTUP_TOOLCHAIN=nightly anchor idl build -o target/idl/phalnx.json

# Run on-chain tests (436 LiteSVM tests — no validator needed)
npx ts-mocha -p ./tsconfig.json -t 300000 \
  tests/phalnx.ts tests/jupiter-integration.ts \
  tests/flash-trade-integration.ts tests/security-exploits.ts \
  tests/instruction-constraints.ts tests/escrow-integration.ts

# Run all TypeScript tests (~637 tests across 5 suites)
pnpm -r run test

# Lint
npm run lint
cargo fmt --check --manifest-path programs/phalnx/Cargo.toml

Test Suites

Suite	Tests
Core vault management & permission engine	108
Jupiter integration (composed swaps)	8
Jupiter Lend integration (deposit/withdraw)	6
Flash Trade integration (leveraged perps)	30
Security exploit scenarios	151
Instruction constraints (generic enforcement)	41
Escrow integration (deposit/settle/refund)	14
Analytics counters (failed TX + per-agent TX count)	7
Devnet integration tests (real network)	69
Surfpool integration tests (local Surfnet)	59
Core policy engine (@phalnx/core)	66
Platform client tests (@phalnx/platform)	17
Crossmint custody adapter	29
Kit-native SDK (@phalnx/kit)	802
Kit SDK devnet tests (@phalnx/kit devnet)	9
SAK plugin (@phalnx/plugin-solana-agent-kit)	6
Rust unit tests (cargo test)	71
Total	1493

Security

• Vulnerability Disclosure Policy
• Security Tools & Scanning
• Published Audit Reports

Raw scan output is stored as private CI artifacts (accessible to repo collaborators only). Published audit reports are added to docs/audits/ after auditor release.

License

This project is licensed under the Apache License 2.0.