@cfxdevkit/services 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to `@cfxdevkit/sdk` will be documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+---
+
+## [0.1.0] - 2026-02-19
+
+### Added
+- Initial SDK extraction from `conflux-devkit` monorepo
+- `clients`: `ClientManager`, `CoreClient`, `EspaceClient` (+ wallet/test variants)
+- `config`: Chain definitions for Conflux Core Space and eSpace (local/testnet/mainnet)
+- `types`: `ChainType`, `UnifiedAccount`, `Address`, `ChainConfig` and all client interfaces
+- `utils`: Simple structured logger
+- `wallet/derivation`: BIP32/BIP39 HD wallet derivation for both Core and eSpace addresses
+- `wallet/session-keys`: `SessionKeyManager` – temporary delegated signing
+- `wallet/batching`: `TransactionBatcher` – multi-tx execution
+- `wallet/embedded`: `EmbeddedWalletManager` – server-side custody
+- `contracts/abis`: ERC-20, ERC-721, ERC-1155 ABIs
+- `contracts/deployer`: `ContractDeployer` – deploy to Core or eSpace
+- `contracts/interaction`: `ContractReader`, `ContractWriter`
+- `services/swap`: `SwapService` – Swappi DEX integration (Uniswap V2)
+- `services/keystore`: `KeystoreService` – encrypted HD wallet storage (AES-256-GCM + PBKDF2)
+- `services/encryption`: `EncryptionService` – AES-256-GCM crypto primitives
+
+### Changed (from conflux-devkit)
+- Removed DevKit backend coupling from all services; services are now standalone classes
+- Removed Solidity compiler wrapper (`solc` dependency)
+- Removed `ui-headless` hooks (were DevKit-API coupled, not wagmi-native)
+- Removed DevNode plugin, CLI binary, MCP server, WebSocket streaming server
+- Fixed `@scure/bip39/wordlists/english` import to use `.js` extension for ESM compatibility
+- Keystore backwards-compatibility block removed (DevKit-specific legacy)
+- `moduleResolution` switched from `node` to `bundler` for correct ESM subpath resolution

package/LICENSE

@@ -0,0 +1,72 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice included in or
+      attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, submitted to the
+      Licensor for inclusion in the Work.
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, use, sell, offer for sale, import, and
+      otherwise transfer the Work.
+
+   Copyright 2025-2026 cfxdevkit
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,257 @@
+# @cfxdevkit/services
+
+> Conflux SDK · blockchain client library for Conflux Core Space & eSpace
+
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+
+Single-package SDK extracted from [conflux-devkit](https://github.com/cfxdevkit/conflux-devkit).  
+Provides chain clients, contract utilities, wallet derivation, swap services, and keystore management for building on Conflux.
+
+---
+
+## Installation
+
+```bash
+pnpm add @cfxdevkit/sdk
+# or
+npm install @cfxdevkit/sdk
+```
+
+Peer dependencies (install if using React hooks):
+
+```bash
+pnpm add react react-dom
+```
+
+---
+
+## Package Structure
+
+| Subpath | Contents |
+|---------|----------|
+| `@cfxdevkit/sdk` | Full barrel – everything |
+| `@cfxdevkit/sdk/clients` | `ClientManager`, `CoreClient`, `EspaceClient` |
+| `@cfxdevkit/sdk/config` | Chain definitions for Core + eSpace |
+| `@cfxdevkit/sdk/types` | Shared TypeScript types |
+| `@cfxdevkit/sdk/utils` | Logger |
+| `@cfxdevkit/sdk/wallet` | HD derivation, session keys, batching, embedded wallets |
+| `@cfxdevkit/sdk/contracts` | `ContractDeployer`, `ContractReader`, `ContractWriter`, ERC ABIs |
+| `@cfxdevkit/sdk/services` | `SwapService` (Swappi DEX), `KeystoreService`, `EncryptionService` |
+| `@cfxdevkit/sdk/automation` | `SafetyGuard`, `RetryQueue`, `PriceChecker`, `AUTOMATION_MANAGER_ABI`, types |
+
+---
+
+## Quick Start
+
+### Connect to Conflux eSpace
+
+```typescript
+import { ClientManager, EVM_MAINNET } from '@cfxdevkit/sdk';
+
+const manager = new ClientManager({
+  evm: { chain: EVM_MAINNET },
+});
+
+await manager.connect();
+const block = await manager.evm.publicClient.getBlockNumber();
+console.log('Current block:', block);
+```
+
+### Connect to Conflux Core Space
+
+```typescript
+import { ClientManager, CORE_MAINNET } from '@cfxdevkit/sdk';
+
+const manager = new ClientManager({
+  core: { chain: CORE_MAINNET },
+});
+
+await manager.connect();
+const epochNumber = await manager.core.publicClient.getEpochNumber();
+console.log('Current epoch:', epochNumber);
+```
+
+### HD Wallet Derivation
+
+```typescript
+import { generateMnemonic, deriveAccounts } from '@cfxdevkit/sdk/wallet';
+
+// Generate new wallet
+const mnemonic = generateMnemonic();
+
+// Derive 5 accounts (both Core & eSpace addresses)
+const accounts = deriveAccounts(mnemonic, { count: 5 });
+
+for (const account of accounts) {
+  console.log(`[${account.index}] Core: ${account.coreAddress}`);
+  console.log(`[${account.index}] eSpace: ${account.evmAddress}`);
+}
+```
+
+### Read an ERC-20 token
+
+```typescript
+import { ClientManager, EVM_MAINNET } from '@cfxdevkit/sdk/clients';
+import { ContractReader } from '@cfxdevkit/sdk/contracts';
+import { ERC20_ABI } from '@cfxdevkit/sdk/contracts';
+
+const manager = new ClientManager({ evm: { chain: EVM_MAINNET } });
+await manager.connect();
+
+const reader = new ContractReader(manager);
+const balance = await reader.read({
+  address: '0x14b2d3bc65e74dae1030eafd8ac30c533c976a9b', // WCFX
+  abi: ERC20_ABI,
+  functionName: 'balanceOf',
+  args: ['0xYourAddress'],
+  chain: 'evm',
+});
+console.log('Balance:', balance);
+```
+
+### Query a DEX swap quote (Swappi)
+
+```typescript
+import { ClientManager, EVM_MAINNET } from '@cfxdevkit/sdk/clients';
+import { SwapService } from '@cfxdevkit/sdk/services';
+
+const manager = new ClientManager({ evm: { chain: EVM_MAINNET } });
+await manager.connect();
+
+const swap = new SwapService(manager.evm.publicClient, 'mainnet');
+const quote = await swap.getQuote({
+  tokenIn: 'WCFX',
+  tokenOut: 'USDT',
+  amountIn: '1',   // 1 WCFX
+  slippageBps: 50, // 0.5%
+});
+console.log('Expected out:', quote.amountOut);
+```
+
+### Encrypted Keystore
+
+```typescript
+import { KeystoreService } from '@cfxdevkit/sdk/services';
+
+const keystore = new KeystoreService('/path/to/.keystore.json');
+await keystore.setup({ password: 'my-password' });
+await keystore.addMnemonic({ mnemonic: 'word1 word2 ...', label: 'main' });
+
+// Later – unlock and derive
+await keystore.unlockKeystore('my-password');
+const accounts = await keystore.deriveAccountsFromMnemonic(
+  mnemonic, 'espace', 5, 0
+);
+```
+
+### Automation (SafetyGuard · RetryQueue · PriceChecker)
+
+```typescript
+import {
+  SafetyGuard, RetryQueue, PriceChecker, AUTOMATION_MANAGER_ABI,
+} from '@cfxdevkit/sdk/automation';
+
+// Injectable logger — pass pino/winston/console or omit for silence
+const guard = new SafetyGuard({ maxSwapUsd: 5_000 }, myLogger);
+const queue = new RetryQueue({ baseDelayMs: 5_000 }, myLogger);
+const checker = new PriceChecker(myPriceSource, tokenPricesUsd, myLogger);
+
+// Pre-flight check before sending a transaction
+const result = guard.check(job, { swapUsd: estimatedUsd });
+if (!result.ok) {
+  queue.enqueue(job);     // schedule retry with exponential backoff
+}
+
+// Check price condition
+const { conditionMet, swapUsd } = await checker.checkLimitOrder(job);
+```
+
+---
+
+## Architecture
+
+```
+@cfxdevkit/sdk
+│
+├── clients/         ← cive (Core) + viem (eSpace) thin wrappers + ClientManager
+├── config/          ← Chain definitions: local / testnet / mainnet for both spaces
+├── types/           ← ChainType, UnifiedAccount, Address, etc.
+├── utils/           ← Logger
+│
+├── wallet/
+│   ├── derivation.ts    ← BIP32/BIP39 HD derivation (Core ↔ eSpace)
+│   ├── session-keys/    ← Temporary delegated signing
+│   ├── batching/        ← Multi-tx batching
+│   └── embedded/        ← Server-side custody
+│
+├── contracts/
+│   ├── abis/            ← ERC20, ERC721, ERC1155
+│   ├── deployer/        ← Deploy to Core or eSpace
+│   └── interaction/     ← ContractReader, ContractWriter
+│
+├── services/
+│   ├── swap.ts          ← Swappi DEX integration (Uniswap V2 style)
+│   ├── keystore.ts      ← Encrypted HD wallet storage (AES-256-GCM)
+│   └── encryption.ts    ← AES-256-GCM + PBKDF2 primitives
+│
+└── automation/          ← Off-chain automation primitives (no pino dep; injectable logger)
+    ├── types.ts         ← Job + safety types (JobStatus, SafetyConfig, …)
+    ├── safety-guard.ts  ← SafetyGuard — off-chain pre-flight checks
+    ├── retry-queue.ts   ← RetryQueue — exponential backoff scheduling
+    ├── price-checker.ts ← PriceChecker — price-source abstraction
+    ├── abi.ts           ← AUTOMATION_MANAGER_ABI (viem `as const`)
+    ├── keeper-interface.ts ← KeeperClient interface
+    └── index.ts         ← Barrel export
+```
+
+---
+
+## Dual-Space Architecture
+
+Conflux has two parallel spaces on the same chain:
+
+| | Core Space | eSpace |
+|--|--|--|
+| **API** | Conflux RPC (Epoch-based) | EVM-compatible JSON-RPC |
+| **Addresses** | `cfx:aaa...` (base32) | `0x...` (hex) |
+| **SDK Client** | `CoreClient` (via `cive`) | `EspaceClient` (via `viem`) |
+| **Native token** | CFX | CFX (same) |
+
+Use `ClientManager` to manage both simultaneously.
+
+---
+
+## Conflux Networks
+
+| Network | Core Chain ID | eSpace Chain ID |
+|---------|--------------|----------------|
+| Mainnet | 1029 | 1030 |
+| Testnet | 1 | 71 |
+| Local | 2029 | 2030 |
+
+---
+
+## Development
+
+```bash
+pnpm install
+pnpm build        # ESM + CJS + .d.ts
+pnpm type-check   # tsc --noEmit
+pnpm test         # vitest
+pnpm test:coverage
+```
+
+---
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE)
+
+---
+
+## Relation to conflux-devkit
+
+This library was extracted from the [conflux-devkit](https://github.com/cfxdevkit/conflux-devkit) monorepo.  
+It contains only production-usable, framework-agnostic code.  
+The DevNode management CLI, MCP server, and dashboard are **not** included.