circle-chain sdk in javascript

The javascript sdk for circle-chain.

User module

The module provides the user services.

Wallet module

The module provides the wallet service.

Block module

The module provides the block service.

install

npm i @lidh04/circle-chain-sdk

CLI

The CLI is built with Commander.js and published as the executable circle on your PATH when you install the package globally.

Install the CLI globally

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

Confirm it is available:

circle --help

Using circle

• -d / --dev — talk to http://localhost:8888 instead of the production API (e.g. circle --dev user login-send-code --email [email protected]).
• Subcommands are grouped under user, wallet, block, miner, and config. Explore each with circle <group> --help.

circle --help
circle user --help
circle user login-send-code --email [email protected]
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

From a clone, build first, then run the same entrypoint via npm or node:

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

CLI unit tests live in src/cli/*.test.js; Jest runs the compiled copies under dist/cjs/cli/ (see jest.config.cjs). Run npm run build before npm test, or use npm run test:cli to build and run only those suites. Jest sets CIRCLE_SKIP_GEO=1 by default via jest.env.cjs so unit tests do not perform outbound Geo requests.

After npm run build, the fixup script marks dist/mjs/cli/main.js as executable so the circle bin can run as a script where your platform supports it.

HTTP API host, timeouts, and GeoIP

The SDK resolves the API base URL (host, protocol, read/write timeouts, etc.) through common.getGatewayHttp(), which merges:

1. Defaults from the bundled circle-gateway.js (e.g. host circle-node.net, HTTPS).
2. Node only — Geo hint: if you do not set host in http.config, the SDK may use ~/.ccl/http-geo.cache: a short-lived result from a Geo lookup (public IP country via https://ipwho.is/).
   • Country code CN → default host from circle-gateway.js (mainland).
   • Any other country → www.circlecoin.me (see GATEWAY_HTTP_HOST_OVERSEAS in circle-common.js).
3. ~/.ccl/http.config: explicit keys override defaults (and an explicit host here disables Geo for host selection).

Browser: no ~/.ccl files; only bundled defaults apply (plus whatever you pass in your own layer).

Environment variables

| Variable | Effect | | -------- | ------ | | CIRCLE_SKIP_GEO=1 | Do not call the Geo IP service or read/write http-geo.cache. Useful for tests or locked-down networks. |

Programmatic API (common)

Re-exported from the package as common on the default export object, or import from the module path you use in your bundler:

import sdk from '@lidh04/circle-chain-sdk';
const { common } = sdk;

// Effective HTTP map (strings), same shape as gateway.http
const http = common.getGatewayHttp();
console.log(http.host, http.protocol, http.timeoutRead);

// Optional: await Geo refresh before first request (Node)
await common.refreshGatewayHttpGeoCache();

// After editing config files on disk
common.clearGatewayHttpCache();

Useful exports include: getGatewayHttp, getUserHttpConfigPath, mergeUserHttpConfig, clearGatewayHttpCache, refreshGatewayHttpGeoCache, gatewayHttpHostForCountry, GATEWAY_HTTP_CONFIG_KEYS, and GATEWAY_HTTP_HOST_OVERSEAS.

Note: On the first run after install, if there is no http-geo.cache yet, the SDK uses the bundled default host until a background lookup completes and writes the cache (unless CIRCLE_SKIP_GEO=1).

getData / postData: On HTTP 200 they return the response body only. On failure or non-200 they return { status, message }. The examples under Usage below often assume an error envelope—adjust checks when you handle raw success payloads.

Usage

First register and login or login with verify code

// 1. you can register your account or just login with verify code
// option 1: register and then login:
const response = await sendRegisterVerifyCode({
    email: "[email protected]"
});
if (response.status !== 200) {
    throw new Error(response.message);
}
//receive the verify code for register.
const regResponse = await register({
    email: "[email protected]",
    passwordInput1: "1111111",
    passwordInput2: "1111111",
    verifyCode: "2222222"
});
if (regResponse.status !== 200) {
    throw new Error(regResponse.message);
}
// register success now. then you can login with password.
const loginResponse = await login({
    email: "[email protected]",
    password: "111111",
});
if (loginResponse.status !== 200) {
    throw new Error(loginResponse.message);
}
// option2: login with verify code without register.
const loginVerifyResponse = await sendVerifyCode({
    email: "[email protected]"
});
if (loginVerifyResponse.status !== 200) {
    throw new Error(loginVerifyResponse.message);
}
// receive the login verify code in your email.
const loginResult = await login({
    email: "[email protected]",
    verifyCode: "222222",
});
if (loginResult.status !== 200) {
    throw new Error(loginResult.message);
}
/// for your login, option1 and option2 are ok, you just select one.
// now you login success here.

Create wallet

const response = await createWallet();
if (response.status !== 200) {
    throw new Error(response.message);
}
const { data: address } = response;
console.log("create wallet success, address:", address);

Mine Block locally

Using your address, mine the block locally in your machine, and get the cc coins now! When you success upload one block, you will get 10cc(100,000li) in your address.

import os from "os";
import sdk from '@lidh04/circle-chain-sdk';

const { miner } = sdk;
async function main() {
  if (!miner.canMineBlock()) {
    return;
  }

  const address = '15ea379mhPvKG95T3MnoCy9xuvTpusnXYx'; // replace your address here!
  const response = await miner.fetchMyBlockData(address);
  console.log("fetchMyBlockData response:", JSON.stringify(response));
  const { status, data } = response;
  if (status === 200 && data) {
    const { blockHeaderHexString, channelId } = data;
    const cpus = os.cpus();
    console.log("find the cpu cores:", cpus.length);
    const result = await miner.mineBlock(blockHeaderHexString, cpus.length - 1);
    console.log("mineBlock result:", JSON.stringify(result));
    if (result) {
      const items = result.split("\n");
      console.log(result);
      const minedBlockHeader = items[0];
      const postResult = await miner.postMyBlock({
        address,
        channelId,
        blockHeaderHexString: minedBlockHeader
      });
      console.log("post mined block result:", JSON.stringify(postResult));
    }
  }
}

main().catch(err => console.error(err));

Set pay password

const response = await sendPayVerifyCode({
    email: '[email protected]'
});
if (response.status !== 200) {
    throw new Error(response.message);
}
// receive the pay verify code in your email.
const setResponse = await setPayPassword({
    account: {
        email: "[email protected]",
    },
    verifyCode: '222222',
    password: '111111'
});
if (setResponse.status !== 200) {
    throw new Error(setResponse.message);
}
// now the pay password is set.

Transactions

const from = '1L8eRrBuWnBxcQ6DKCDkkPM7ozxDcmpho1';
const to = '14hF1BynFVnBEFKxyo51FHmJksVwfxg4sg';
// send asset from `1L8eRrBuWnBxcQ6DKCDkkPM7ozxDcmpho1` to `14hF1BynFVnBEFKxyo51FHmJksVwfxg4sg`
const response = await sendTo({
    email: '[email protected]',
    from,
    address: to,
    transContent: {
        type: 1,
        uuid: 'e1f1d3c7-3c6e-4f3b-a50d-58710b851357'
    },
    payPassword: '111111'
});
if (response.status !== 200) {
    throw new Error(response.message);
}
// the asset is sent success.

// pay balance from `1L8eRrBuWnBxcQ6DKCDkkPM7ozxDcmpho1` to `14hF1BynFVnBEFKxyo51FHmJksVwfxg4sg`
response = await pay({
    from,
    to,
    value: 100,
    payPassword: "111111"
});
if (response.status !== 200) {
    throw new Error(response.message);
}
// the value is paid success.

Add contacts

const response = await addContacts({
    email: "[email protected]",
    name: "test2",
    sex: 1,
    address: "beijing"
});
if (response.status !== 200) {
    throw new Error(response.message);
}
// the contact is added success.

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

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

1.0.22

• improve the sdk security.

1.0.21

• fix some bugs.

1.0.20

• support mine block locally