Registry
Supported networks
Capability is stated per chain. “Plan-only” means ZeFi understands the chain well enough to route to it but holds no wallet connection there.
| Network | Chain id | Native | Capability | Explorer |
|---|---|---|---|---|
| Ethereum | 1 | ETH | Read and execute | etherscan.io |
| Base | 8453 | ETH | Read and execute | basescan.org |
| Arbitrum One | 42161 | ETH | Read and execute | arbiscan.io |
| OP Mainnet | 10 | ETH | Read and execute | optimistic.etherscan.io |
| Polygon PoS | 137 | POL | Read and execute | polygonscan.com |
| Solana | — | SOL | Plan only | solscan.io |
Verified assets
DAIETHPOLSOLUSDCUSDTWBTCWETH
Addresses and decimals for these assets are curated and stored EIP-55 checksummed. A test asserts every address in the registry is a valid checksummed address, so a typo fails the build rather than reaching a user. Any asset outside this list requires an explicit contract address — ZeFi will not guess one.
Intent categories
- EXPLAIN
- PORTFOLIO_QUERY
- SEND
- SWAP
- BRIDGE
- APPROVE
- CONTRACT_INTERACTION
- COMPARE_ROUTES
- ROUTEFOLD_ANALYSIS
- UNKNOWN
SEND, SWAP, BRIDGE, APPROVE and CONTRACT_INTERACTION are transactional and produce a plan. The rest are answered directly.
Plan statuses
- draft — Draft
- missing_information — Missing information
- ready_to_simulate — Ready to simulate
- simulating — Simulating
- simulation_passed — Simulation passed
- simulation_warning — Simulation warning
- ready_for_signature — Ready for signature
- submitted — Submitted
- confirmed — Confirmed
- failed — Failed
- cancelled — Cancelled
Transitions are enforced by an explicit state machine. An invalid transition throws rather than silently succeeding; confirmed, failed and cancelled are terminal.
Configuration
Environment variables
Every variable ZeFi reads. Absent credentials produce a labelled, degraded mode — never a silent fallback and never a fabricated value.
Core
- DATABASE_URL
- PostgreSQL connection string. Omit to run without persistence.
- NEXT_PUBLIC_APP_URL
- Canonical public URL. Defaults to https://zefi.ae.
Authentication
- NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
- Clerk publishable key.
- CLERK_SECRET_KEY
- Clerk secret key. Server-only.
- NEXT_PUBLIC_CLERK_SIGN_IN_URL
- Defaults to /sign-in.
- NEXT_PUBLIC_CLERK_SIGN_UP_URL
- Defaults to /sign-up.
AI
- AI_PROVIDER
- openai (default) or anthropic. Unset auto-selects whichever is fully configured.
- OPENAI_API_KEY
- OpenAI API key.
- OPENAI_MODEL
- Model identifier. Never hardcoded in source — set what your key can access.
- OPENAI_BASE_URL
- Optional. For an Azure or OpenAI-compatible gateway.
- ANTHROPIC_API_KEY
- Alternative provider key.
- ANTHROPIC_MODEL
- Alternative provider model identifier.
- AI_MAX_TOKENS
- Optional. Defaults to 2048.
- AI_TIMEOUT_MS
- Optional. Defaults to 45000.
Wallet & RPC
- NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID
- Enables the WalletConnect connector when present.
- RPC_URL_ETHEREUM
- Server-side endpoint. Public fallback used when unset.
- RPC_URL_BASE
- Server-side endpoint.
- RPC_URL_ARBITRUM
- Server-side endpoint.
- RPC_URL_OPTIMISM
- Server-side endpoint.
- RPC_URL_POLYGON
- Server-side endpoint.
Feature flags
- TRANSACTION_EXECUTION_ENABLED
- Master switch for requesting wallet signatures. Defaults to false.
- DEMO_MODE
- Serves labelled fixtures when credentials are absent. Never a silent fallback.
- NEXT_PUBLIC_ROUTEFOLD_URL
- Public URL of a separate Routefold deployment.
Provider-ready
- SIMULATION_PROVIDER
- Enables deep simulation. Unset means local validation only.
- SWAP_PROVIDER
- Enables swap route quotes and calldata.
- BRIDGE_PROVIDER
- Enables bridge route comparison and calldata.
- PORTFOLIO_PROVIDER
- Enables USD pricing for volatile assets.
Running ZeFi
Commands
pnpm installInstall dependenciespnpm db:migrateApply migrations to a local databasepnpm db:seedSeed labelled demo data for one userpnpm devStart the development serverpnpm lintLintpnpm typecheckType-check with no emitpnpm testUnit and integration testspnpm test:e2ePlaywright smoke tests against a production buildpnpm buildProduction build
Full setup, architecture and deployment notes live in the repository: README.md, ARCHITECTURE.md, SECURITY.md, DEPLOYMENT.md, TRANSACTION_SAFETY.md and AI_SYSTEM.md. See also how it works for the capability matrix.