Skip to content

Commit 4422bf3

Browse files
SPCFXDASPCFXDA
committed
docs: add March 2026 monthly report
1 parent aa4cb9f commit 4422bf3

File tree

1 file changed

+389
-0
lines changed

1 file changed

+389
-0
lines changed

‎docs/MONTHLY_REPORT_2026-03-14.md‎

Lines changed: 389 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,389 @@
1+
# Monthly Report — March 2026
2+
3+
**Period:** 2026-03-01 → 2026-03-14
4+
**Repository:** [@cfxdevkit/devkit monorepo](https://github.com/cfxdevkit/devkit)
5+
**Total commits:** 59
6+
**Packages released:** v1.0.14 → v1.0.15 → v1.0.16 (all 12 managed packages across 3 patch releases)
7+
8+
---
9+
10+
## Overview
11+
12+
March consolidates the monorepo started in January/February into a
13+
production-ready state. Three categories of work are tracked:
14+
15+
- **New** — packages, apps, or infrastructure that did not exist before March.
16+
- **Update** — shipping improvements, fixes, or new features on top of
17+
already-delivered work (including the CAS app, which is a bounty winner now
18+
being refactored and hardened for production deployment).
19+
- **Maintenance** — version bumps, dependency updates, and release pipeline
20+
fixes with no functional source changes.
21+
22+
The monorepo now ships 12 published `@cfxdevkit/*` packages, a live
23+
documentation site with auto-generated API references, a full-stack reference
24+
application (CAS), a wallet-connect + SIWE developer starter template, and a
25+
complete CI/CD + ARM64 VPS deployment stack.
26+
27+
---
28+
29+
## NEW — `@cfxdevkit/theme` v1.0.0 — Tailwind CSS preset & design tokens
30+
31+
**Note:** Package created this month; not yet published to npm (internal monorepo dependency).
32+
**Commit:** `0d04d9d`
33+
34+
Brand new package. Provides a shared Tailwind CSS preset and global CSS
35+
variables (design tokens) consumed by both `@cfxdevkit/react` and the CAS /
36+
template frontends, keeping visual consistency across all UI surfaces without
37+
duplicating configuration.
38+
39+
- `src/tailwind/preset.ts` — Tailwind preset with Conflux brand palette,
40+
typography scale, and component token names.
41+
- `src/css/globals.css` — CSS custom properties for spacing, radius, and colour
42+
tokens; auto-imported by consuming apps.
43+
- Exported as both ESM and CJS via `tsup`; included in the unified v1.0.16
44+
release.
45+
46+
---
47+
48+
## NEW — `@cfxdevkit/wallet-connect` — wagmi v2 + ConnectKit + SIWE for Conflux
49+
50+
**npm:** [npmjs.com/package/@cfxdevkit/wallet-connect](https://www.npmjs.com/package/@cfxdevkit/wallet-connect)
51+
**Commits:** `ef64437`, `0878b58`, `61abdeb`, `50bb71d`, `634d5df`, `a1bfa22`,
52+
`c7295c4`, `fcb377d`, `d552856`, `fd70964`, `e9e3935`, `33cbe7d`
53+
54+
New package delivering the full browser wallet connection layer for Conflux
55+
eSpace applications. The package stub existed in the initial monorepo commit;
56+
all functional implementation landed in March.
57+
58+
New files in this release: `chains.ts` (Conflux eSpace chain configs for wagmi),
59+
`server.ts` (SIWE message verification helpers), `useIsAdmin.ts` (session-based
60+
admin role hook), `ConnectModalContext` (decoupled `ConnectKit` provider wiring).
61+
62+
**SIWE auto-sign hardening** (12 commits) resolved a cluster of reliability
63+
issues when testing against MetaMask, WalletConnect v2, Brave Wallet, and
64+
Coinbase Wallet:
65+
66+
- **Double-init guard:** `WalletConnect EthereumProvider` was instantiated twice
67+
causing duplicate subscribe events.
68+
- **`ConnectKit` hook scope:** `useModal()` context boundary (`ConnectModalContext`)
69+
decouples hook from provider timing.
70+
- **Turbopack module deduplication:** `connectkit` resolved to a single instance
71+
via `turbopack.resolveAlias` to avoid RSC/client split.
72+
- **Synchronous `chainId`:** `window.ethereum.chainId` read synchronously;
73+
dropped async `eth_chainId` RPC call which introduced a race condition.
74+
- **Auto-sign guard:** SIWE signature blocked until chain switch confirmed;
75+
`switchChainAsync` awaited for EIP-3085 fallback; ref reset on login failure.
76+
- **`appUrl`:** derived from `window.location.origin` at runtime.
77+
- **`dev:https` script:** local TLS support for Brave's HTTP→HTTPS upgrade.
78+
79+
---
80+
81+
## NEW — `@cfxdevkit/defi-react` — `PoolsProvider` + `useTokenPrice` hooks
82+
83+
**npm:** [npmjs.com/package/@cfxdevkit/defi-react](https://www.npmjs.com/package/@cfxdevkit/defi-react)
84+
**Commit:** `0d04d9d`
85+
86+
Two new React hooks added to the existing `@cfxdevkit/defi-react` package
87+
(which previously only exported `usePoolTokens`), enabling full DeFi UI
88+
composition in the CAS frontend:
89+
90+
- `PoolsProvider` — React context provider that fetches live Swappi pool data
91+
and makes it available to child components without prop-drilling.
92+
- `useTokenPrice` — hook that resolves USD price for any eSpace token by
93+
querying the Swappi pair graph, using WCFX as the reference asset.
94+
95+
Both hooks consume `@cfxdevkit/services/swap` internally and are tested against
96+
the EVM_TESTNET endpoint.
97+
98+
---
99+
100+
## NEW — `@cfxdevkit/executor` — `automation.ts` on-chain automation primitives
101+
102+
**npm:** [npmjs.com/package/@cfxdevkit/executor](https://www.npmjs.com/package/@cfxdevkit/executor)
103+
**Commit:** `0d04d9d`
104+
105+
New `automation.ts` module in the existing `@cfxdevkit/executor` package. Adds
106+
high-level helpers used by the CAS backend to manage the on-chain strategy
107+
lifecycle: job registration, state machine transitions, and keeper-compatible
108+
execution payloads. Exposed as a new named export in the package's public API
109+
via `tsup.config.ts` subpath update.
110+
111+
---
112+
113+
## NEW — docs-site: TypeDoc API reference + Mermaid architecture diagrams
114+
115+
**Live site:** [cfxdevkit.org](https://cfxdevkit.org)
116+
**Commits:** `66afab5`, `1e12f01`, `c326633`, `41c4d4a`, `743a706`
117+
118+
The Nextra docs-site already existed (scaffolded in February). The TypeDoc API
119+
reference and architecture diagram layer are new additions this month:
120+
121+
- `scripts/generate-api-docs.mjs` — Turborepo build step that runs TypeDoc over
122+
all 12 package source trees and outputs MDX files consumed by Nextra.
123+
- `components/Mermaid.tsx` — client component wrapping `mermaid.js` for
124+
rendering the monorepo dependency-layer diagram in the architecture page.
125+
- `content/architecture.mdx` — new page with Layer 0/1/2 architecture diagrams.
126+
- `content/api/index.mdx` — API reference landing page with per-package links.
127+
- Fixed 928 TypeDoc warnings; corrected three classes of broken links (`.md`
128+
suffixes in hrefs, `Type.Name` → `Type-Name` slug normalisation, missing
129+
package-slug prefixes on overview pages).
130+
131+
---
132+
133+
## NEW — `apps/template` — wallet-connect + SIWE developer starter kit
134+
135+
**Commits:** `77d1058`, `38be586`, `aa4cb9f`
136+
137+
Minimal but production-ready starter app that developers can fork to bootstrap
138+
a Conflux dApp. Built from scratch in March as a companion to CAS, demonstrating
139+
the minimal integration surface of `@cfxdevkit/wallet-connect`.
140+
141+
- **Frontend:** Next.js 15 (App Router) + wagmi v2 + ConnectKit + SIWE; pre-wired
142+
for Conflux eSpace mainnet and testnet via `@cfxdevkit/core/config` chain
143+
constants.
144+
- **Backend:** Fastify stub with SIWE JWT issuance; Drizzle ORM + better-sqlite3.
145+
- **CI/CD:** dedicated `build-template.yml` + `deploy-template.yml` GitHub
146+
Actions workflows; deploys independently under its own Caddy virtual host on
147+
the shared VPS.
148+
149+
---
150+
151+
## NEW — CI/CD: GitHub Actions build / deploy / release pipeline
152+
153+
**Commits:** `0c49d15`, `c6c93a8`, `d3e8ce8`, `38be586`, `0b596a3`
154+
155+
Four new workflows covering CAS and template application delivery (the `ci.yml`
156+
and `release.yml` workflows pre-existed for package publishing):
157+
158+
| Workflow | Trigger | Purpose |
159+
|---|---|---|
160+
| `build-cas.yml` | push to main (paths filter) + `workflow_dispatch` | Build + push `cas-backend` Docker image to GHCR |
161+
| `build-template.yml` | push to main (paths filter) | Build + push `template-backend` image |
162+
| `deploy-cas.yml` | after `build-cas` succeeds | SSH → Hetzner VPS, `docker pull` + `docker-compose up -d` |
163+
| `deploy-template.yml` | after `build-template` succeeds | Same for template |
164+
165+
`pnpm-lock.yaml` added to paths filters; `workflow_dispatch` added to
166+
`build-cas` for emergency hot-fixes that bypass the paths match.
167+
168+
---
169+
170+
## NEW — Ansible VPS provisioning: Hetzner CAX11 (ARM64) — 5 roles
171+
172+
**Commits:** `0c49d15`, `2712af5`, `60fe69a`, `18c5be9`, `df96cef`
173+
174+
Complete idempotent Ansible playbook in `infra/ansible/` for provisioning the
175+
production Hetzner CAX11 ARM64 server from a bare Ubuntu image:
176+
177+
| Role | Responsibility |
178+
|---|---|
179+
| `base` | Security hardening, `deploy` user, NOPASSWD sudo, SSH key injection |
180+
| `docker` | Docker Engine + Compose V2 |
181+
| `caddy` | Reverse proxy with automatic TLS; virtual hosts for CAS, template, monitoring |
182+
| `backups` | restic daily snapshots to Backblaze B2 |
183+
| `monitoring` | Uptime Kuma healthcheck container |
184+
185+
Four bootstrap fixes corrected flag-ordering bugs that prevented provisioning a
186+
fresh VPS: VPS is now fully reproducible with a single `ansible-playbook` run.
187+
188+
---
189+
190+
## UPDATE — CAS app: production refactoring & deployment (bounty winner)
191+
192+
**Commits:** `0c49d15`, `881fe45`, `4218528`, `f1707bc`, `f7db078`, `0d04d9d`,
193+
`b48bc7b`, `d66cb74`, `f1f1827`, `52d9a5c`, `878ea22`, `b8e0cf2`, `c4d5ca8`,
194+
`169fada`, `d267264`, `bb4fac5`, `2896998`, `54983cf`, `666d690`
195+
196+
The Conflux Automation Site (CAS) was a prior bounty winner. This month it was
197+
refactored and integrated into the `@cfxdevkit` monorepo as `apps/cas/`, wired
198+
to the full `@cfxdevkit/*` SDK stack, and hardened for production deployment.
199+
Work is ongoing (WIP).
200+
201+
**Backend refactoring (Fastify + Drizzle + better-sqlite3):**
202+
- SIWE-issued JWT auth middleware; public `/api/status` for health monitoring.
203+
- Drizzle ORM schema for jobs, users, pool state.
204+
- Docker data volume wired; `DATABASE_PATH` env injection.
205+
- GHCR image path corrected to `ghcr.io/cfxdevkit/devkit/cas-backend`.
206+
207+
**Frontend refactoring (Next.js 15 + wagmi v2 + ConnectKit):**
208+
- SSR wagmi client deduplication (single instance across RSC/client boundary).
209+
- Dashboard, StrategyBuilder, SafetyPanel, ApprovalWidget components.
210+
- Network switch banner; SIWE auto-sign flow.
211+
212+
**Docker multi-arch build resolution (10 commits):**
213+
Shipping a `linux/amd64` CI-built image for an ARM64 VPS with `better-sqlite3`
214+
(a native Node.js addon) required resolving a multi-architecture compilation
215+
problem. After five failed approaches (pnpm deploy dropping binaries, symlink
216+
breaks, QEMU SIGILL, `.npmrc` timeout), the solution was switching from
217+
`node:20-slim` to `node:20` which ships prebuilt ARM64 binaries for
218+
`better-sqlite3`, eliminating all native compilation under QEMU. Dockerfile
219+
rewritten with `turbo prune` stage for minimal build context.
220+
221+
---
222+
223+
## UPDATE — `@cfxdevkit/core` v1.0.16 — browser compatibility + client refactor
224+
225+
**npm:** [npmjs.com/package/@cfxdevkit/core](https://www.npmjs.com/package/@cfxdevkit/core)
226+
**Commits:** `301a98e`, `63757e7`, `01577a8`
227+
228+
- Replaced `node:events` with `eventemitter3` in `ClientManager` so the package
229+
works in browser bundlers (Next.js, Vite) without a Node.js polyfill shim —
230+
unblocked the docs-site from using the package directly.
231+
- Internal client modules (`clients/core.ts`, `clients/evm.ts`,
232+
`clients/manager.ts`) refactored; `utils/logger.ts` and `utils/index.ts`
233+
updated.
234+
- `src/__tests__/playground-examples.test.ts` added; tests run the same code
235+
snippets shown in the interactive playground, ensuring examples stay in sync.
236+
237+
---
238+
239+
## UPDATE — `@cfxdevkit/react` v1.0.16 — `AppNavBar` component
240+
241+
**npm:** [npmjs.com/package/@cfxdevkit/react](https://www.npmjs.com/package/@cfxdevkit/react)
242+
**Commit:** `0d04d9d`
243+
244+
New `AppNavBar` component added to `src/components/nav/`. A responsive navigation
245+
bar pre-configured for Conflux dApps — wraps the ConnectKit connect button,
246+
network indicator, and slot for app-specific nav items. Used directly in both
247+
the CAS and template frontends via `@cfxdevkit/react`.
248+
249+
---
250+
251+
## UPDATE — `@cfxdevkit/services` v1.0.16 — swap service update
252+
253+
**npm:** [npmjs.com/package/@cfxdevkit/services](https://www.npmjs.com/package/@cfxdevkit/services)
254+
**Commit:** `0d04d9d`
255+
256+
`src/services/swap.ts` and `src/services/index.ts` updated to expose additional
257+
swap path utilities needed by the new `useTokenPrice` hook in `@cfxdevkit/defi-react`.
258+
259+
---
260+
261+
## UPDATE — `@cfxdevkit/contracts` v1.0.16 — standard ABI test suite
262+
263+
**npm:** [npmjs.com/package/@cfxdevkit/contracts](https://www.npmjs.com/package/@cfxdevkit/contracts)
264+
**Commit:** `0c49d15`
265+
266+
`src/standard-abis.test.ts` added — verifies that all canonical ERC ABI
267+
exports (`erc20Abi`/`ERC20_ABI`, `erc721Abi`/`ERC721_ABI`, etc.) are
268+
well-formed and that both camelCase and UPPER_CASE exports are present and
269+
equal. Prevents regressions from codegen drift.
270+
271+
---
272+
273+
## UPDATE — docs-site: Sandpack playground examples
274+
275+
**Commits:** `8995e9c`, `c6f48a4`, `1b0f38c`, `a65e0d5`, `1518735`
276+
277+
The Sandpack interactive playground existed in the docs-site before March.
278+
Updated this month:
279+
280+
- All examples rewritten to use `EVM_TESTNET` and live `@cfxdevkit/*` packages.
281+
- New example tabs: `@cfxdevkit/wallet` (HD derivation) and `@cfxdevkit/contracts`
282+
(ABI lookup).
283+
- `viem` pinned to `2.46.2` to fix `Math.pow` BigInt error in the browser
284+
sandbox.
285+
- Top-level `await` wrapped in async IIFEs for Sandpack compatibility.
286+
- Six EIP-55 address checksums corrected.
287+
288+
---
289+
290+
## UPDATE — Release pipeline: `pnpm pack` normalisation + v1.0.14→v1.0.16
291+
292+
**Commits:** `5916779`, `3359113`, `3d7a35e`, `28a828e`
293+
294+
Three patch releases shipped on 2026-03-01:
295+
296+
- **v1.0.14 → v1.0.15:** Fixed `node:events` browser incompatibility in
297+
`@cfxdevkit/core` (see core entry above).
298+
- **v1.0.15 → v1.0.16:** Fixed `workspace:*` dependencies not being resolved to
299+
semver ranges on publish — the release script now runs `pnpm pack` as a
300+
pre-publish verification step.
301+
302+
Packages with version bump only (no source changes this month):
303+
`@cfxdevkit/compiler`, `@cfxdevkit/devnode`, `@cfxdevkit/protocol`,
304+
`@cfxdevkit/wallet`.
305+
306+
---
307+
308+
## UPDATE — Dev tooling: pre-commit hooks + lint-staged + Biome enforcement
309+
310+
**Commits:** `2672055`, `01577a8`, `4218528`
311+
312+
`simple-git-hooks` + `lint-staged` added at the workspace root. Pre-commit hook
313+
runs `biome check --write` on staged `.ts/.tsx/.json` files, blocking commits
314+
that introduce lint/format regressions. One pre-existing violation fixed
315+
immediately in `@cfxdevkit/core` (string concat → template literal, `useTemplate`
316+
rule). All 59 March commits pass `pnpm check` clean.
317+
318+
---
319+
320+
## Maintenance — `@cfxdevkit/compiler` v1.0.16
321+
322+
**npm:** [npmjs.com/package/@cfxdevkit/compiler](https://www.npmjs.com/package/@cfxdevkit/compiler)
323+
324+
Version bump to v1.0.16 as part of the unified monorepo release. No functional
325+
source changes. Updated `package.json` dependency ranges to reflect the new
326+
`@cfxdevkit/core@^1.0.16` minimum.
327+
328+
---
329+
330+
## Maintenance — `@cfxdevkit/devnode` v1.0.16
331+
332+
**npm:** [npmjs.com/package/@cfxdevkit/devnode](https://www.npmjs.com/package/@cfxdevkit/devnode)
333+
334+
Version bump to v1.0.16. No functional source changes. Updated dependency ranges.
335+
336+
---
337+
338+
## Maintenance — `@cfxdevkit/protocol` v1.0.16
339+
340+
**npm:** [npmjs.com/package/@cfxdevkit/protocol](https://www.npmjs.com/package/@cfxdevkit/protocol)
341+
342+
Version bump to v1.0.16. No functional source changes. Updated dependency ranges.
343+
344+
---
345+
346+
## Maintenance — `@cfxdevkit/wallet` v1.0.16
347+
348+
**npm:** [npmjs.com/package/@cfxdevkit/wallet](https://www.npmjs.com/package/@cfxdevkit/wallet)
349+
350+
Version bump to v1.0.16. No functional source changes. Updated dependency ranges.
351+
352+
---
353+
354+
## Maintenance — `conflux-devkit` v1.0.16 — local development node manager
355+
356+
**npm:** [npmjs.com/package/conflux-devkit](https://www.npmjs.com/package/conflux-devkit)
357+
358+
`conflux-devkit` is the `npx conflux-devkit` CLI tool that starts and manages a
359+
local Conflux development node. Receives the same unified version bump as all
360+
monorepo packages. No functional source changes this month; version bump ensures
361+
consumers using `npx conflux-devkit@latest` always get the matching release.
362+
363+
---
364+
365+
## Summary Table
366+
367+
| # | Task | Type | npm |
368+
|---|---|---|---|
369+
| 1 | `@cfxdevkit/theme` — new Tailwind CSS preset package (not yet on npm) | NEW | — |
370+
| 2 | `@cfxdevkit/wallet-connect` — SIWE + ConnectKit full implementation | NEW | [↗](https://www.npmjs.com/package/@cfxdevkit/wallet-connect) |
371+
| 3 | `@cfxdevkit/defi-react` — PoolsProvider + useTokenPrice hooks | NEW | [↗](https://www.npmjs.com/package/@cfxdevkit/defi-react) |
372+
| 4 | `@cfxdevkit/executor` — automation.ts on-chain automation primitives | NEW | [↗](https://www.npmjs.com/package/@cfxdevkit/executor) |
373+
| 5 | docs-site: TypeDoc API reference + Mermaid architecture diagrams | NEW | — |
374+
| 6 | apps/template — wallet-connect + SIWE developer starter | NEW | — |
375+
| 7 | CI/CD: build/deploy GitHub Actions workflows (4 new) | NEW | — |
376+
| 8 | Ansible VPS provisioning — Hetzner CAX11, 5 roles | NEW | — |
377+
| 9 | CAS app — production refactoring & deployment (bounty winner WIP) | UPDATE | — |
378+
| 10 | `@cfxdevkit/core` — browser compat + client refactor + playground tests | UPDATE | [↗](https://www.npmjs.com/package/@cfxdevkit/core) |
379+
| 11 | `@cfxdevkit/react` — AppNavBar component | UPDATE | [↗](https://www.npmjs.com/package/@cfxdevkit/react) |
380+
| 12 | `@cfxdevkit/services` — swap service update | UPDATE | [↗](https://www.npmjs.com/package/@cfxdevkit/services) |
381+
| 13 | `@cfxdevkit/contracts` — standard ABI test suite | UPDATE | [↗](https://www.npmjs.com/package/@cfxdevkit/contracts) |
382+
| 14 | docs-site: Sandpack playground examples rewrite | UPDATE | — |
383+
| 15 | Release pipeline v1.0.14→v1.0.16 + pnpm pack normalisation | UPDATE | — |
384+
| 16 | Dev tooling: pre-commit hooks + lint-staged | UPDATE | — |
385+
| 17 | `@cfxdevkit/compiler` v1.0.16 — maintenance release | MAINTENANCE | [↗](https://www.npmjs.com/package/@cfxdevkit/compiler) |
386+
| 18 | `@cfxdevkit/devnode` v1.0.16 — maintenance release | MAINTENANCE | [↗](https://www.npmjs.com/package/@cfxdevkit/devnode) |
387+
| 19 | `@cfxdevkit/protocol` v1.0.16 — maintenance release | MAINTENANCE | [↗](https://www.npmjs.com/package/@cfxdevkit/protocol) |
388+
| 20 | `@cfxdevkit/wallet` v1.0.16 — maintenance release | MAINTENANCE | [↗](https://www.npmjs.com/package/@cfxdevkit/wallet) |
389+
| 21 | `conflux-devkit` v1.0.16 — local dev node CLI maintenance release | MAINTENANCE | [↗](https://www.npmjs.com/package/conflux-devkit) |

0 commit comments

Comments
 (0)