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.

CommandPurposecircle config showPrint 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:

ExportDescriptiongetGatewayHttp()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_KEYSArray of accepted config keys.GATEWAY_HTTP_HOST_OVERSEASHost 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).