Skip to content

Latest commit

 

History

History
319 lines (239 loc) · 13.9 KB

AGENT-CONTEXT.md

File metadata and controls

319 lines (239 loc) · 13.9 KB

Agent Context — Machine-Readable Codebase Map

This document is designed to be consumed by AI coding assistants. It provides a structured map of the @cfxdevkit monorepo so that an agent can quickly orient itself without reading every file.

Repository root: /workspaces/repos

packages/          @cfxdevkit/* published npm packages
devtools/          private tooling (Hardhat, CLI server, Next.js UI)
docs/              documentation
docker/            Dockerfile + docker-compose.yml
scripts/           release.mjs, setup-npm-trust.mjs
biome.json         lint/format config (root + per-package overrides)
turbo.json         build pipeline
pnpm-workspace.yaml
tsconfig.base.json  shared tsconfig (extended per package)

Published packages

@cfxdevkit/core (packages/core/)

Purpose: Foundation layer. RPC clients, HD wallet, contract utilities, chain configs, automation primitives.

Key exports (from packages/core/src/):

  • ClientManager — manages viem (eSpace) + cive (Core Space) clients
  • EVM_MAINNET, EVM_TESTNET, EVM_LOCAL, CORE_MAINNET, CORE_TESTNET, CORE_LOCAL — chain configs
  • ContractReader, ContractWriter, ContractDeployer — contract interaction
  • generateMnemonic, deriveAccounts, deriveAccount — HD wallet BIP32/BIP39
  • EmbeddedWalletManager, TransactionBatcher, SessionKeyManager — wallet types
  • ERC20_ABI, ERC721_ABI, ERC1155_ABI, ERC2612_ABI, ERC4626_ABI — standard ABIs (re-exported from @cfxdevkit/contracts)
  • erc20Abi, erc721Abi, erc1155Abi, erc2612Abi, erc4626Abi — camelCase aliases
  • SafetyGuard, RetryQueue, PriceChecker — automation primitives (from /automation subpath)

Subpath exports: /clients, /config, /types, /utils, /wallet, /contracts, /automation

Source tree: packages/core/src/{clients,config,types,utils,wallet,contracts,automation}/

@cfxdevkit/contracts (packages/contracts/)

Purpose: All on-chain artifacts — generated DevKit ABIs, canonical standard token ABIs, bootstrap library (deployable templates).

Key exports (from packages/contracts/src/):

  • Generated DevKit contracts (from src/generated.ts):
    • automationManagerAbi, automationManagerAddress, automationManagerBytecode, automationManagerConfig
    • permitHandlerAbi, permitHandlerAddress, permitHandlerBytecode, permitHandlerConfig
    • swappiPriceAdapterAbi, swappiPriceAdapterAddress, swappiPriceAdapterBytecode, swappiPriceAdapterConfig
    • UPPER_CASE aliases: AUTOMATION_MANAGER_ABI, PERMIT_HANDLER_ABI, SWAPPI_PRICE_ADAPTER_ABI
  • Standard ABIs (from src/standard-abis.ts):
    • erc20Abi / ERC20_ABI, erc20ExtendedAbi / ERC20_EXTENDED_ABI
    • erc721Abi / ERC721_ABI, erc721ExtendedAbi / ERC721_EXTENDED_ABI
    • erc1155Abi / ERC1155_ABI
    • erc2612Abi / ERC2612_ABI
    • erc4626Abi / ERC4626_ABI
  • Bootstrap library (from src/bootstrap-abis.ts):
    • erc20BaseAbi, erc20BaseBytecode — full-featured ERC-20 (cap, burn, pause, permit, RBAC)
    • erc721BaseAbi, erc721BaseBytecode — full-featured ERC-721 NFT (enumerable, URI, royalties)
    • erc1155BaseAbi, erc1155BaseBytecode — full-featured ERC-1155 (per-token caps, royalties)
    • wrappedCfxAbi, wrappedCfxBytecode — WETH9-identical CFX wrapper
    • stakingRewardsAbi, stakingRewardsBytecode — Synthetix-style staking
    • vestingScheduleAbi, vestingScheduleBytecode — cliff + linear vesting
    • merkleAirdropAbi, merkleAirdropBytecode — Merkle proof airdrop
    • multiSigWalletAbi, multiSigWalletBytecode — M-of-N multisig
    • paymentSplitterAbi, paymentSplitterBytecode — proportional revenue splitter
    • mockPriceOracleAbi, mockPriceOracleBytecode — Chainlink AggregatorV3 mock

Do not edit: src/generated.ts and src/bootstrap-abis.ts are auto-generated by pnpm --filter @cfxdevkit/contracts-dev codegen.

@cfxdevkit/protocol (packages/protocol/)

Purpose: Conflux precompile ABIs + deprecated DevKit ABI re-exports.

Key exports (from packages/protocol/src/precompiles.ts):

  • adminControlAbi / ADMIN_CONTROL_ABI + adminControlAddress (0x0888…0000)
  • sponsorWhitelistAbi / SPONSOR_WHITELIST_ABI + sponsorWhitelistAddress (0x0888…0001)
  • stakingAbi / STAKING_ABI + stakingAddress (0x0888…0002)
  • crossSpaceCallAbi / CROSS_SPACE_CALL_ABI + crossSpaceCallAddress (0x0888…0006)
  • posRegisterAbi / POS_REGISTER_ABI + posRegisterAddress (0x0888…0005)
  • CONFLUX_PRECOMPILE_ADDRESSES — named map of all addresses

Deprecated re-exports (from src/abi.ts, will be removed in v2):

  • automationManagerAbi, permitHandlerAbi, swappiPriceAdapterAbi + their UPPER_CASE/address/bytecode/config variants
  • Migration: change from '@cfxdevkit/protocol' → from '@cfxdevkit/contracts'

@cfxdevkit/services (packages/services/)

Purpose: Stateful services built on top of @cfxdevkit/core — encrypted keystore, Swappi DEX, AES-256 encryption.

Key exports:

  • KeystoreService — file-backed encrypted HD wallet keystore (AES-256-GCM + PBKDF2)
    • setup(opts), addMnemonic(opts), unlockKeystore(pw), lock()
    • getActiveMnemonic(), deriveAccountsFromMnemonic(mnemonic, space, count, offset)
  • SwapService — Swappi DEX router (Uniswap V2 style)
    • getQuote({tokenIn, tokenOut, amountIn, slippageBps}) → quote
    • swap({...quote, walletClient, deadline}) → txHash
    • getTokenInfo(symbol) → token metadata
  • EncryptionService — AES-256-GCM + PBKDF2
    • encrypt(data, password), decrypt(encrypted, password)

@cfxdevkit/executor (packages/executor/)

Purpose: On-chain strategy execution engine for Conflux.

Key exports:

  • Executor — orchestrates job evaluation, price checks, on-chain execution
  • KeeperClientImpl — viem wrapper for AutomationManager contract
  • SafetyGuard — circuit-breaker with per-tick swap caps, retry caps, consecutive failure circuit-breaker
  • RetryQueue — exponential backoff with jitter
  • PriceChecker — pluggable price source + condition evaluation (gte/lte)
  • noopLogger — silent AutomationLogger implementation
  • Job types: LimitOrderJob, DCAJob, TWAPJob, SwapJob (union: Job)
  • Strategy types: LimitOrderStrategy, DCAStrategy, TWAPStrategy, SwapStrategy

Import: all from @cfxdevkit/executor (no subpaths)

@cfxdevkit/wallet (packages/wallet/)

Purpose: Thin re-export facade over @cfxdevkit/core/wallet. Use when you only need wallet features.

Key exports: TransactionBatcher, SessionKeyManager, EmbeddedWalletManager (same as @cfxdevkit/core/wallet)

Subpaths: @cfxdevkit/wallet/batching, @cfxdevkit/wallet/session-keys, @cfxdevkit/wallet/embedded

@cfxdevkit/compiler (packages/compiler/)

Purpose: Runtime Solidity compilation (no Hardhat binary required) + pre-built templates.

Key exports:

  • compileSolidity(input) → CompilationResult
  • compileMultipleSources(sources, optimizer?, evmVersion?) → CompilationResult
  • getSolcVersion() → string
  • getSimpleStorageContract(), getTestTokenContract() — memoised pre-built templates
  • TEST_CONTRACTS — map of all templates (via @cfxdevkit/compiler/templates subpath)

Important: always uses EVM version paris (Conflux eSpace doesn't support PUSH0/shanghai).

@cfxdevkit/devnode (packages/devnode/)

Purpose: Programmatic wrapper for @xcfx/node local Conflux dev environment.

Key exports:

  • ServerManager — start/stop node, mine blocks, list accounts, get RPC URLs
    • start(), stop(), mine(n), startMining(intervalMs), stopMining()
    • getAccounts(), getRpcUrls(), getNodeStatus()

@cfxdevkit/defi-react (packages/defi-react/)

Purpose: DeFi React hooks — Swappi pool token resolution with on-chain balance enrichment.

Key exports:

  • usePoolTokens({ poolsApiUrl, chain, address }) → { tokens, pairs, isLoading, error }
  • getPairedTokens(pairs, tokenInAddress) → filtered token list
  • AUTOMATION_MANAGER_ABI, ERC20_ABI, WCFX_ABI, MAX_UINT256 — re-exported constants

@cfxdevkit/react (packages/react/)

Purpose: Unstyled headless React components and hooks for Conflux UI.

Key exports:

  • DevKitProvider — RPC endpoint + wallet context provider
  • useBalance, useContract, useTransaction — Conflux-aware hooks
  • ConnectButton, AccountCard, ContractReader, ContractWriter, SwapWidget — UI components

@cfxdevkit/wallet-connect (packages/wallet-connect/)

Purpose: wagmi v2 + ConnectKit + SIWE wallet connection layer, pre-configured for Conflux.

Key exports:

  • AuthProvider — wraps wagmi + tanstack/react-query + ConnectKit + SIWE session
  • WalletConnect — modal-based connect button
  • useAuthContext() → { address, isAuthenticated, signIn, signOut }
  • useNetworkSwitch() — switch between Conflux networks
  • wagmiConfig — pre-configured Conflux eSpace mainnet + testnet + local
  • confluxESpace, confluxESpaceTestnet — viem chain objects

Devtools

devtools/contracts (devtools/contracts/)

Hardhat project. Source contracts are in devtools/contracts/contracts/:

  • AutomationManager.sol — on-chain keeper registry
  • SwappiPriceAdapter.sol — Swappi DEX price feed
  • PermitHandler.sol — EIP-2712 permit relay
  • interfaces/ — ABI interfaces
  • mocks/ — test mocks (MockPriceOracle, etc.)
  • Bootstrap templates in subdirectory

Hardhat config: devtools/contracts/hardhat.config.ts
Wagmi codegen config: devtools/contracts/wagmi.config.ts

devtools/devkit (devtools/devkit/)

Express + Socket.IO server + CLI.

Source structure:

devtools/devkit/src/
├── cli.ts                          # CLI entry point (commander)
└── server/
    ├── index.ts                    # Express app setup, middleware, route mounting
    ├── node-manager.ts             # @xcfx/node process wrapper
    ├── ws.ts                       # WebSocket / Socket.IO setup
    ├── deploy-helpers.ts           # orchestrateDeploy() helper
    ├── contract-storage.ts         # JSON-file contract registry
    └── routes/
        ├── devnode.ts              # POST /api/devnode/start|stop; GET /status
        ├── accounts.ts             # GET /api/accounts; POST /fund
        ├── contracts.ts            # compile, deploy, call, write
        ├── bootstrap.ts            # catalog, catalog/:name, deploy
        ├── mining.ts               # mine, start, stop
        ├── network.ts              # GET/PUT /api/network
        └── keystore.ts             # setup, unlock, lock, status

devtools/devkit-ui (devtools/devkit-ui/)

Next.js 14 static export. Pages in devtools/devkit-ui/src/app/:

  • (dashboard)/node/ — Node tab
  • (dashboard)/accounts/ — Accounts tab
  • (dashboard)/contracts/ — Contracts tab
  • (dashboard)/bootstrap/ — Bootstrap catalog + precompile reference tab
  • (dashboard)/mining/ — Mining tab
  • (dashboard)/network/ — Network tab
  • (dashboard)/wallet/ — Wallet & keystore tab

Built output goes to devtools/devkit/ui/ and is served as static files by the CLI server.

Common patterns

Adding a new exported function to a package

  1. Add the implementation to packages/<pkg>/src/
  2. Re-export from packages/<pkg>/src/index.ts
  3. If adding a subpath, update packages/<pkg>/package.json "exports" and tsup.config.ts

Adding a new contract template (bootstrap)

  1. Write the Solidity in devtools/contracts/contracts/
  2. Add it to devtools/contracts/wagmi.config.ts
  3. Run pnpm --filter @cfxdevkit/contracts-dev codegen
  4. The new ABI/bytecode will appear in packages/contracts/src/bootstrap-abis.ts
  5. Import it in devtools/devkit/src/server/routes/bootstrap.ts and add a catalog entry

Running tests for a single package

pnpm --filter @cfxdevkit/<pkg> test
pnpm --filter @cfxdevkit/<pkg> test:coverage

Type-checking without building

pnpm type-check
# or single package:
pnpm --filter @cfxdevkit/<pkg> type-check

Import path cheat sheet

What you need Import from
EVM RPC client @cfxdevkit/core → ClientManager (.evm)
Core Space RPC client @cfxdevkit/core → ClientManager (.core)
Contract read @cfxdevkit/core → ContractReader
Contract write @cfxdevkit/core → ContractWriter
Contract deploy @cfxdevkit/core → ContractDeployer
HD wallet key derivation @cfxdevkit/core or @cfxdevkit/wallet
Encrypted keystore @cfxdevkit/services → KeystoreService
Swappi DEX swap @cfxdevkit/services → SwapService
AES-256 encryption @cfxdevkit/services → EncryptionService
Standard ERC-20/721/1155 ABI @cfxdevkit/contracts → erc20Abi etc.
EIP-2612 permit ABI @cfxdevkit/contracts → erc2612Abi
ERC-4626 vault ABI @cfxdevkit/contracts → erc4626Abi
DevKit contract ABI @cfxdevkit/contracts → automationManagerAbi etc.
Bootstrap contract ABI/bytecode @cfxdevkit/contracts → erc20BaseAbi etc.
Conflux precompile ABI @cfxdevkit/protocol → adminControlAbi etc.
Solidity compile (runtime) @cfxdevkit/compiler → compileSolidity
Pre-built contract templates @cfxdevkit/compiler → TEST_CONTRACTS
Execution engine (keeper) @cfxdevkit/executor → Executor
Local dev node (programmatic) @cfxdevkit/devnode → ServerManager
Local dev node (browser UI) npx conflux-devkit
React wallet connect button @cfxdevkit/wallet-connect → WalletConnect
React auth context @cfxdevkit/wallet-connect → useAuthContext
wagmi config @cfxdevkit/wallet-connect → wagmiConfig
DeFi React hooks @cfxdevkit/defi-react → usePoolTokens
Headless React components @cfxdevkit/react → DevKitProvider etc.