Skip to content

Commit 9616988

Browse files
SPCFXDASPCFXDA
committed
docs: add missing READMEs for contracts, defi-react, executor, protocol; add Codecov to CI
1 parent d122838 commit 9616988

File tree

5 files changed

+394
-1
lines changed

5 files changed

+394
-1
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,14 @@ jobs:
122122
- name: Run tests with coverage
123123
run: pnpm test
124124

125-
- name: Upload coverage reports
125+
- name: Upload coverage to Codecov
126+
uses: codecov/codecov-action@v5
127+
with:
128+
token: ${{ secrets.CODECOV_TOKEN }}
129+
files: packages/*/coverage/lcov.info,devtools/*/coverage/lcov.info
130+
fail_ci_if_error: true
131+
132+
- name: Upload coverage artifacts
126133
if: always()
127134
uses: actions/upload-artifact@v4
128135
with:

‎packages/contracts/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# @cfxdevkit/contracts
2+
3+
Auto-generated, type-safe ABI and deployment artifacts for the Conflux DevKit on-chain contracts.
4+
5+
## What's included
6+
7+
| Export | Description |
8+
|---|---|
9+
| `automationManagerAbi` / `AUTOMATION_MANAGER_ABI` | Type-safe ABI for the `AutomationManager` contract |
10+
| `automationManagerAddress` | Deployed addresses per chain ID (`1030` mainnet, `71` testnet) |
11+
| `automationManagerBytecode` | Deployment bytecode |
12+
| `automationManagerConfig` | Combined config object (abi + address) for wagmi/viem |
13+
| `permitHandlerAbi` / `PERMIT_HANDLER_ABI` | ABI for the `PermitHandler` contract |
14+
| `permitHandlerAddress` | Deployed addresses per chain ID |
15+
| `permitHandlerBytecode` | Deployment bytecode |
16+
| `swappiPriceAdapterAbi` / `SWAPPI_PRICE_ADAPTER_ABI` | ABI for the `SwappiPriceAdapter` contract |
17+
| `swappiPriceAdapterAddress` | Deployed addresses per chain ID |
18+
| `swappiPriceAdapterBytecode` | Deployment bytecode |
19+
20+
Each contract is exported both as `camelCase` (wagmi/viem idiomatic) and `UPPER_CASE` (legacy compatibility).
21+
22+
## Installation
23+
24+
```bash
25+
pnpm add @cfxdevkit/contracts
26+
# or
27+
npm install @cfxdevkit/contracts
28+
```
29+
30+
## Peer dependencies
31+
32+
```json
33+
{
34+
"viem": ">=2.0.0"
35+
}
36+
```
37+
38+
## Usage
39+
40+
### With viem
41+
42+
```ts
43+
import { createPublicClient, http } from 'viem';
44+
import { confluxESpace } from 'viem/chains';
45+
import { automationManagerAbi, automationManagerAddress } from '@cfxdevkit/contracts';
46+
47+
const client = createPublicClient({
48+
chain: confluxESpace,
49+
transport: http(),
50+
});
51+
52+
const jobCount = await client.readContract({
53+
address: automationManagerAddress[1030],
54+
abi: automationManagerAbi,
55+
functionName: 'jobCount',
56+
});
57+
```
58+
59+
### With wagmi
60+
61+
```ts
62+
import { useReadContract } from 'wagmi';
63+
import { automationManagerConfig } from '@cfxdevkit/contracts';
64+
65+
const { data: jobCount } = useReadContract({
66+
...automationManagerConfig,
67+
functionName: 'jobCount',
68+
chainId: 1030,
69+
});
70+
```
71+
72+
## Regenerating artifacts
73+
74+
Artifacts are generated from the Hardhat workspace and should never be edited by hand:
75+
76+
```bash
77+
pnpm --filter @cfxdevkit/contracts codegen
78+
# equivalent to: cd devtools/contracts && hardhat compile && wagmi generate
79+
```
80+
81+
## Conflux Compatibility
82+
83+
| Network | Chain ID | Support |
84+
|---|---|---|
85+
| Conflux eSpace Mainnet | 1030 | ✅ |
86+
| Conflux eSpace Testnet | 71 | ✅ (when deployed) |

‎packages/defi-react/README.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# @cfxdevkit/defi-react
2+
3+
DeFi React hooks for Conflux DevKit — Swappi pool token resolution with on-chain balance enrichment.
4+
5+
## Features
6+
7+
- **`usePoolTokens`** — Fetches the full Swappi token list from your backend, enriches each entry with the connected wallet's live on-chain balance (batched via Multicall3), and caches aggressively in `localStorage` so the UI is instant on re-mount.
8+
- **`getPairedTokens`** — Filter helper to get all tokens paired with a given `tokenIn` address.
9+
- **CFX native support** — A synthetic "CFX (native)" entry at the EIP-7528 sentinel address is included alongside the WCFX ERC-20.
10+
- **Resilience** — Token/pair lists only grow, never shrink. A flaky RPC response that temporarily drops entries cannot remove them from the UI.
11+
- **Contract constants** — Re-exports `AUTOMATION_MANAGER_ABI`, `ERC20_ABI`, `WCFX_ABI`, and `MAX_UINT256` for convenience.
12+
13+
## Installation
14+
15+
```bash
16+
pnpm add @cfxdevkit/defi-react
17+
# or
18+
npm install @cfxdevkit/defi-react
19+
```
20+
21+
## Peer dependencies
22+
23+
```json
24+
{
25+
"react": ">=18",
26+
"viem": ">=2.0.0"
27+
}
28+
```
29+
30+
## Usage
31+
32+
### `usePoolTokens`
33+
34+
```tsx
35+
import { usePoolTokens } from '@cfxdevkit/defi-react';
36+
37+
function TokenSelector() {
38+
const { tokens, pairs, isLoading, error } = usePoolTokens({
39+
/** URL of your backend /api/pools endpoint */
40+
poolsApiUrl: '/api/pools',
41+
/** viem chain — confluxESpace or confluxESpaceTestnet */
42+
chain: confluxESpace,
43+
/** Connected wallet address (or undefined if not connected) */
44+
address: walletAddress,
45+
});
46+
47+
if (isLoading) return <p>Loading tokens…</p>;
48+
if (error) return <p>Error: {error.message}</p>;
49+
50+
return (
51+
<ul>
52+
{tokens.map((t) => (
53+
<li key={t.address}>
54+
{t.symbol} — {t.balanceFormatted}
55+
</li>
56+
))}
57+
</ul>
58+
);
59+
}
60+
```
61+
62+
### `getPairedTokens`
63+
64+
```ts
65+
import { getPairedTokens } from '@cfxdevkit/defi-react';
66+
67+
// Get all tokens that can be swapped with WCFX
68+
const options = getPairedTokens(pairs, wcfxAddress);
69+
```
70+
71+
### Contract constants
72+
73+
```ts
74+
import {
75+
AUTOMATION_MANAGER_ABI,
76+
ERC20_ABI,
77+
WCFX_ABI,
78+
MAX_UINT256,
79+
} from '@cfxdevkit/defi-react';
80+
```
81+
82+
## Conflux Compatibility
83+
84+
| Network | Chain | Support |
85+
|---|---|---|
86+
| Conflux eSpace Mainnet | `confluxESpace` (1030) | ✅ |
87+
| Conflux eSpace Testnet | `confluxESpaceTestnet` (71) | ✅ |

‎packages/executor/README.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# @cfxdevkit/executor
2+
3+
On-chain strategy execution engine for Conflux DevKit — the runtime primitives for building keepers, bots, or AI agents that execute limit orders, DCA, TWAP, and spot swaps on Conflux eSpace.
4+
5+
## Features
6+
7+
- **`Executor`** — Orchestrator that evaluates jobs on a tick interval, checks price conditions, enforces safety limits, and submits on-chain transactions.
8+
- **`KeeperClientImpl`** — viem-based client that wraps the `AutomationManager` contract for job creation, cancellation, and forceful execution.
9+
- **`SafetyGuard`** — Circuit-breaker with configurable per-tick swap caps, per-job retry caps, and a global circuit-breaker on consecutive failures.
10+
- **`RetryQueue`** — Exponential backoff with jitter for failed job retries.
11+
- **`PriceChecker`** — Pluggable price source interface + condition evaluator (`gte`/`lte` against a target price).
12+
- **Full type system** — `Job` union type with per-strategy params (`LimitOrderJob`, `DCAJob`, `TWAPJob`, `SwapJob`) and lifecycle statuses.
13+
- **Zero framework coupling** — Injectable `AutomationLogger` interface; no React, no HTTP framework required.
14+
15+
## Supported strategies
16+
17+
| Strategy | Status |
18+
|---|---|
19+
| Limit order | ✅ Implemented |
20+
| DCA (Dollar-Cost Averaging) | ✅ Implemented |
21+
| TWAP | 🔜 Types only (contract support pending) |
22+
| Spot swap | 🔜 Types only (contract support pending) |
23+
24+
## Installation
25+
26+
```bash
27+
pnpm add @cfxdevkit/executor
28+
# or
29+
npm install @cfxdevkit/executor
30+
```
31+
32+
## Peer dependencies
33+
34+
```json
35+
{
36+
"viem": ">=2.0.0"
37+
}
38+
```
39+
40+
## Usage
41+
42+
### Basic keeper setup
43+
44+
```ts
45+
import { Executor, KeeperClientImpl, SafetyGuard, PriceChecker, noopLogger } from '@cfxdevkit/executor';
46+
import { createWalletClient, http } from 'viem';
47+
import { confluxESpace } from 'viem/chains';
48+
import { privateKeyToAccount } from 'viem/accounts';
49+
50+
const account = privateKeyToAccount('0x...');
51+
const walletClient = createWalletClient({ account, chain: confluxESpace, transport: http() });
52+
53+
const keeperClient = new KeeperClientImpl({
54+
walletClient,
55+
automationManagerAddress: '0x...',
56+
});
57+
58+
const safetyGuard = new SafetyGuard({
59+
maxSwapsPerTick: 3,
60+
maxConsecutiveFailures: 5,
61+
maxRetriesPerJob: 4,
62+
});
63+
64+
const priceChecker = new PriceChecker({
65+
priceSource: myPriceSource, // implement PriceSource interface
66+
decimalsResolver: myResolver, // implement DecimalsResolver interface
67+
});
68+
69+
const executor = new Executor({
70+
keeperClient,
71+
safetyGuard,
72+
priceChecker,
73+
jobStore: myJobStore, // implement JobStore interface
74+
logger: noopLogger, // or inject your own AutomationLogger
75+
tickIntervalMs: 15_000, // evaluate jobs every 15 s
76+
});
77+
78+
executor.start();
79+
```
80+
81+
### Creating a limit order job
82+
83+
```ts
84+
import type { LimitOrderStrategy } from '@cfxdevkit/executor';
85+
86+
const strategy: LimitOrderStrategy = {
87+
kind: 'limit_order',
88+
tokenIn: '0xCFX...',
89+
tokenOut: '0xUSDT...',
90+
amountIn: '100.0', // human-readable
91+
targetPrice: '0.38', // trigger when price >= target
92+
direction: 'gte',
93+
slippageBps: 50, // 0.5%
94+
expiresInDays: 7,
95+
};
96+
97+
await executor.createJob(strategy, ownerAddress);
98+
```
99+
100+
### Creating a DCA job
101+
102+
```ts
103+
import type { DCAStrategy } from '@cfxdevkit/executor';
104+
105+
const strategy: DCAStrategy = {
106+
kind: 'dca',
107+
tokenIn: '0xUSDT...',
108+
tokenOut: '0xCFX...',
109+
amountPerSwap: '50.0', // human-readable, per interval
110+
intervalHours: 24,
111+
totalSwaps: 30,
112+
slippageBps: 100, // 1%
113+
};
114+
115+
await executor.createJob(strategy, ownerAddress);
116+
```
117+
118+
## Job lifecycle
119+
120+
```
121+
pending → active → executed
122+
↘ failed (exhausted retries)
123+
→ cancelled (user-cancelled)
124+
→ paused (SafetyGuard circuit-breaker)
125+
```
126+
127+
## Conflux Compatibility
128+
129+
| Network | Chain ID | Support |
130+
|---|---|---|
131+
| Conflux eSpace Mainnet | 1030 | ✅ |
132+
| Conflux eSpace Testnet | 71 | ✅ |

0 commit comments

Comments
 (0)