circle-chain-skill

原始内容

---
name: circle-chain-js-sdk
description: JavaScript SDK and CLI for Circle Chain (@lidh04/circle-chain-sdk): user auth,
  wallet, block, miner, transfers, contacts, HTTP config. Global CLI binary `circle`. Use when
  working in js-circle-chain-sdk, integrating Circle Chain from Node/browser, or
  when the user mentions circle-chain SDK, @lidh04/circle-chain-sdk, local mining,
  or the circle CLI.
---

# Circle Chain JavaScript SDK

## Package and layout

- **npm**: `@lidh04/circle-chain-sdk` — local dependency: `npm i @lidh04/circle-chain-sdk`
- **Default export**: an object with namespaces `user`, `wallet`, `block`, `node`, `miner`, `common` — e.g. `import sdk from '@lidh04/circle-chain-sdk'` then `const { user, wallet, miner } = sdk`. README snippets use bare names like `login`, `createWallet`; bind them from the matching namespace (`user.login`, `wallet.createWallet`, etc.).
- **Source repo**: `src/` — `circle-user.js`, `circle-wallet.js`, `circle-block.js`, `circle-node.js`, `circle-miner.js`, `circle-common.js`; CLI under `src/cli/`.

## Development workflow

1. **Build**: `npm run build` — outputs `dist/cjs` and `dist/mjs` (TypeScript + fixup).
2. **Tests**: Run `npm run build` before `npm test` when suites need fresh `dist/`. CLI-only: `npm run test:cli` (builds, then Jest matches `dist/cjs/cli`).
3. **CLI from a clone**: after build, `npm run cli -- <args>` or `node ./dist/mjs/cli/main.js <args>`.

## CLI (Commander.js)

Published executable name: **`circle`** (see `package.json` `"bin"` → `dist/mjs/cli/main.js`).

### Install globally

```bash
npm install -g @lidh04/circle-chain-sdk
circle --help
```

### Using `circle`

- **`-d` / `--dev`** — use `http://localhost:8888` instead of production (e.g. `circle --dev user login-send-code --email you@example.com`).
- Subcommand groups: **user**, **wallet**, **block**, **miner**, **config**. Discover flags with `circle <group> --help`.

```bash
circle --help
circle user --help
circle user login-send-code --email you@example.com
circle wallet query public-balance --address <addr>
circle block header-list --base-height 0
circle miner mine --address <your-miner-address>
circle config show
circle config set --host your.api.example --timeout-read 8000
```

### `circle config` (HTTP settings)

User overrides are stored under **`~/.ccl/`** (or `%USERPROFILE%\.ccl\` on Windows) and apply to the Node.js SDK and CLI.

| Command | Purpose |
| -------- | -------- |
| `circle config show` | Print **effective** HTTP settings (bundled defaults + `http.config` + Geo hint when applicable). |
| `circle config set …` | Merge options into **`~/.ccl/http.config`** (JSON). At least one flag required. |

Supported flags for `config set`:

- `--host`, `--protocol` (`http` \| `https`)
- `--timeout-read`, `--timeout-write` (milliseconds, non‑negative integers as strings in config)
- `--retry-count`, `--retry-wait-time`
- `--ssl-support` (`true` \| `false`)

Example:

```bash
circle config set --host api.example.com --protocol https
```

### Developing this repo

```bash
npm run build
npm run cli -- --help
# or: node ./dist/mjs/cli/main.js --help
```

CLI tests: `src/cli/*.test.js`; Jest runs compiled tests under `dist/cjs/cli/` per `jest.config.cjs`.

## Programmatic usage patterns

Responses typically include `status` (e.g. `200`), `message`, and `data`. On failure, surface `response.message`.

### Auth (register / login)

1. **Register then password login**: `sendRegisterVerifyCode` → `register` → `login` (email + password).
2. **Login with verify code only**: `sendVerifyCode` → `login` (email + `verifyCode`).

### Wallet

- **`createWallet()`** — on success, address in `data`.

### Local mining

1. `miner.canMineBlock()` — return early if false.
2. `miner.fetchMyBlockData(address)` — from `data`: `blockHeaderHexString`, `channelId`.
3. `miner.mineBlock(blockHeaderHexString, workerCount)` — e.g. `os.cpus().length - 1`; result lines separated by `\n`; first line is mined header hex.
4. `miner.postMyBlock({ address, channelId, blockHeaderHexString: minedBlockHeader })`.
5. Per README: successful block upload rewards **10 cc** (**100,000 li**) to the miner address.

### Pay password

- `sendPayVerifyCode` → `setPayPassword` with `account: { email }`, `verifyCode`, `password`.

### Transfers

- **`sendTo`**: `email`, `from`, `address` (to), `transContent` (`type`, `uuid`, etc.), `payPassword`.
- **`pay`**: `from`, `to`, `value`, `payPassword`.

### Contacts

- **`addContacts`**: e.g. `email`, `name`, `sex`, `address` (location string in README).

### `common` namespace (HTTP config & GeoIP)

Available via `import sdk from '@lidh04/circle-chain-sdk'` then `sdk.common.*`.

**Key exports:**

| Export | Description |
|--------|------------|
| `getGatewayHttp()` | Resolve effective HTTP settings (defaults → Geo hint → user `http.config`). Returns object with `host`, `protocol`, `timeoutRead`, `timeoutWrite`, `retryCount`, `retryWaitTime`, `sslSupport`. |
| `mergeUserHttpConfig(updates)` | Write key/value pairs to `~/.ccl/http.config`. |
| `getUserHttpConfigPath()` | Return path to `~/.ccl/http.config`. |
| `clearGatewayHttpCache()` | Invalidate in-memory cache for config and Geo host hint. |
| `refreshGatewayHttpGeoCache()` | Force refresh GeoIP lookup (Node only). |
| `gatewayHttpHostForCountry(countryCode)` | Return API host for a given ISO country code (CN → bundled default; others → `GATEWAY_HTTP_HOST_OVERSEAS`). |
| `GATEWAY_HTTP_CONFIG_KEYS` | Array of accepted config keys. |
| `GATEWAY_HTTP_HOST_OVERSEAS` | Host string for non-mainland regions: `www.circlecoin.me`. |

**GeoIP behavior (Node.js only):**

- On first call to `getGatewayHttp()` without a valid `~/.ccl/http-geo.cache`, the SDK fetches your public IP country from `https://ipwho.is/`.
- **CN** country code → keeps the bundled default host (circle-node.net).
- **Any other** country → uses `www.circlecoin.me` (overseas host).
- Result is cached to `~/.ccl/http-geo.cache` with a 7-day TTL.
- Setting an explicit `host` in `http.config` **disables Geo-based host selection**.
- Disable entirely with environment variable `CIRCLE_SKIP_GEO=1`.

## Versions

### 1.1.2
- **HTTP config:** user overrides in `~/.ccl/http.config` (JSON); `common.getGatewayHttp()` merges defaults from `circle-gateway.js`, optional Geo-based host hint, then `http.config` (explicit `host` wins and skips Geo for host).
- **GeoIP (Node):** `~/.ccl/http-geo.cache` populated via `https://ipwho.is/`; mainland **CN** keeps default API host; other regions use **`www.circlecoin.me`**. Disable with **`CIRCLE_SKIP_GEO=1`**. Helpers: `refreshGatewayHttpGeoCache()`, `gatewayHttpHostForCountry()`, `clearGatewayHttpCache()`.
- **CLI:** `circle config show` / `circle config set` for HTTP settings; build **`fixup`** sets execute bit on CLI `main.js`.
- **Tests:** shared `expectSdkHttpResult` for live API shape; `circle-common-geo.test.js`; Jest `jest.env.cjs` for `CIRCLE_SKIP_GEO`.

### 1.1.1
- README: document global CLI install (`npm install -g @lidh04/circle-chain-sdk`), using `circle` with `--dev`, and developing the repo (`npm run cli` / `node ./dist/mjs/cli/main.js`)

### 1.1.0

- CLI (Commander.js) for user, wallet, miner, block; entry **`circle`** / `main.js`.
- CLI split into `user-command`, `wallet-command`, `miner-command`, `block-command`; user CLI email-only.
- CLI tests under `src/cli`, Jest runs `dist/cjs/cli`; `circle-node` test import path fix.

### 1.0.22 — security improvements  
### 1.0.21 — bugfixes  
### 1.0.20 — local block mining

Keep this skill aligned with repo `README.md` and `package.json` (bin name, exports).

name: circle-chain-js-sdk description: JavaScript SDK and CLI for Circle Chain (@lidh04/circle-chain-sdk): user auth, wallet, block, miner, transfers, contacts, HTTP config. Global CLI binary `circle`. Use when working in js-circle-chain-sdk, integrating Circle Chain from Node/browser, or when the user mentions circle-chain SDK, @lidh04/circle-chain-sdk, local mining, or the circle CLI.

Circle Chain JavaScript SDK

Package and layout

npm: @lidh04/circle-chain-sdk — local dependency: npm i @lidh04/circle-chain-sdk
Default export: an object with namespaces user, wallet, block, node, miner, common — e.g. import sdk from '@lidh04/circle-chain-sdk' then const { user, wallet, miner } = sdk. README snippets use bare names like login, createWallet; bind them from the matching namespace (user.login, wallet.createWallet, etc.).
Source repo: src/ — circle-user.js, circle-wallet.js, circle-block.js, circle-node.js, circle-miner.js, circle-common.js; CLI under src/cli/.

Development workflow

Build: npm run build — outputs dist/cjs and dist/mjs (TypeScript + fixup).
Tests: Run npm run build before npm test when suites need fresh dist/. CLI-only: npm run test:cli (builds, then Jest matches dist/cjs/cli).
CLI from a clone: after build, npm run cli -- <args> or node ./dist/mjs/cli/main.js <args>.

CLI (Commander.js)

Published executable name: circle (see package.json "bin" → dist/mjs/cli/main.js).

Install globally

npm install -g @lidh04/circle-chain-sdk
circle --help

Using `circle`

-d / --dev — use http://localhost:8888 instead of production (e.g. circle --dev user login-send-code --email you@example.com).
Subcommand groups: user, wallet, block, miner, config. Discover flags with circle <group> --help.

circle --help
circle user --help
circle user login-send-code --email you@example.com
circle wallet query public-balance --address <addr>
circle block header-list --base-height 0
circle miner mine --address <your-miner-address>
circle config show
circle config set --host your.api.example --timeout-read 8000

`circle config` (HTTP settings)

User overrides are stored under ~/.ccl/ (or %USERPROFILE%\.ccl\ on Windows) and apply to the Node.js SDK and CLI.

Command	Purpose
`circle config show`	Print effective HTTP settings (bundled defaults + `http.config` + Geo hint when applicable).
`circle config set …`	Merge options into `~/.ccl/http.config` (JSON). At least one flag required.

Supported flags for config set:

--host, --protocol (http | https)
--timeout-read, --timeout-write (milliseconds, non‑negative integers as strings in config)
--retry-count, --retry-wait-time
--ssl-support (true | false)

Example:

circle config set --host api.example.com --protocol https

Developing this repo

npm run build
npm run cli -- --help
# or: node ./dist/mjs/cli/main.js --help

CLI tests: src/cli/*.test.js; Jest runs compiled tests under dist/cjs/cli/ per jest.config.cjs.

Programmatic usage patterns

Responses typically include status (e.g. 200), message, and data. On failure, surface response.message.

Auth (register / login)

Register then password login: sendRegisterVerifyCode → register → login (email + password).
Login with verify code only: sendVerifyCode → login (email + verifyCode).

Wallet

createWallet() — on success, address in data.

Local mining

miner.canMineBlock() — return early if false.
miner.fetchMyBlockData(address) — from data: blockHeaderHexString, channelId.
miner.mineBlock(blockHeaderHexString, workerCount) — e.g. os.cpus().length - 1; result lines separated by \n; first line is mined header hex.
miner.postMyBlock({ address, channelId, blockHeaderHexString: minedBlockHeader }).
Per README: successful block upload rewards 10 cc (100,000 li) to the miner address.

Pay password

sendPayVerifyCode → setPayPassword with account: { email }, verifyCode, password.

Transfers

sendTo: email, from, address (to), transContent (type, uuid, etc.), payPassword.
pay: from, to, value, payPassword.

Contacts

addContacts: e.g. email, name, sex, address (location string in README).

`common` namespace (HTTP config & GeoIP)

Available via import sdk from '@lidh04/circle-chain-sdk' then sdk.common.*.

Key exports:

Export	Description
`getGatewayHttp()`	Resolve effective HTTP settings (defaults → Geo hint → user `http.config`). Returns object with `host`, `protocol`, `timeoutRead`, `timeoutWrite`, `retryCount`, `retryWaitTime`, `sslSupport`.
`mergeUserHttpConfig(updates)`	Write key/value pairs to `~/.ccl/http.config`.
`getUserHttpConfigPath()`	Return path to `~/.ccl/http.config`.
`clearGatewayHttpCache()`	Invalidate in-memory cache for config and Geo host hint.
`refreshGatewayHttpGeoCache()`	Force refresh GeoIP lookup (Node only).
`gatewayHttpHostForCountry(countryCode)`	Return API host for a given ISO country code (CN → bundled default; others → `GATEWAY_HTTP_HOST_OVERSEAS`).
`GATEWAY_HTTP_CONFIG_KEYS`	Array of accepted config keys.
`GATEWAY_HTTP_HOST_OVERSEAS`	Host string for non-mainland regions: `www.circlecoin.me`.

GeoIP behavior (Node.js only):

On first call to getGatewayHttp() without a valid ~/.ccl/http-geo.cache, the SDK fetches your public IP country from https://ipwho.is/.
CN country code → keeps the bundled default host (circle-node.net).
Any other country → uses www.circlecoin.me (overseas host).
Result is cached to ~/.ccl/http-geo.cache with a 7-day TTL.
Setting an explicit host in http.config disables Geo-based host selection.
Disable entirely with environment variable CIRCLE_SKIP_GEO=1.

Versions

1.1.2

HTTP config: user overrides in ~/.ccl/http.config (JSON); common.getGatewayHttp() merges defaults from circle-gateway.js, optional Geo-based host hint, then http.config (explicit host wins and skips Geo for host).
GeoIP (Node): ~/.ccl/http-geo.cache populated via https://ipwho.is/; mainland CN keeps default API host; other regions use www.circlecoin.me. Disable with CIRCLE_SKIP_GEO=1. Helpers: refreshGatewayHttpGeoCache(), gatewayHttpHostForCountry(), clearGatewayHttpCache().
CLI: circle config show / circle config set for HTTP settings; build fixup sets execute bit on CLI main.js.
Tests: shared expectSdkHttpResult for live API shape; circle-common-geo.test.js; Jest jest.env.cjs for CIRCLE_SKIP_GEO.

1.1.1

README: document global CLI install (npm install -g @lidh04/circle-chain-sdk), using circle with --dev, and developing the repo (npm run cli / node ./dist/mjs/cli/main.js)

1.1.0

CLI (Commander.js) for user, wallet, miner, block; entry circle / main.js.
CLI split into user-command, wallet-command, miner-command, block-command; user CLI email-only.
CLI tests under src/cli, Jest runs dist/cjs/cli; circle-node test import path fix.

1.0.22 — security improvements

1.0.21 — bugfixes

1.0.20 — local block mining

Keep this skill aligned with repo README.md and package.json (bin name, exports).