@sagachain/client

JavaScript client library for SagaChain (WebSocket API, transactions, registry), plus Node CLIs.

Install

npm install @sagachain/client

After install, saga-cli.js and saga-run.js are included in the package (along with py/). This package declares npm bin entries so you can run:

| Command | Script | |---------|--------| | sagachain-cli | saga-cli.js | | sagachain-run | saga-run.js |

From a project that depends on @sagachain/client:

npx sagachain-cli --help
npx sagachain-run --help

(or use the same names in your "scripts" field in package.json; npm puts them on PATH when you run npm run …)

Without bin / explicit path (always works):

node node_modules/@sagachain/client/saga-cli.js --help
node node_modules/@sagachain/client/saga-run.js --help

Global install (npm install -g @sagachain/client) also exposes sagachain-cli and sagachain-run on your shell PATH.

Library (sagachain-lib.js)

ES module entry: @sagachain/client.

import {
  init,
  signAndSendTransaction,
  keygen,
} from '@sagachain/client';

Call init(apiUrl) before sending transactions (you may omit the argument if the URL is set in env—see below). Resolution order: import.meta.env.VITE_API, then on Node process.env.API or process.env.VITE_API (same as the CLI). Those values are applied when you call init() without a URL and whenever internal ensureAPI() runs before requests.

See Environment for a concise table.

Exported symbols

Grouped by role (all are named exports).

| Group | Exports | |--------|---------| | Constants | OVERLAY_TIMEOUT, SystemAccount, ZeroPrivKey, SYS_CLS | | Connection | init, reconnect, disconnect, isSocketConnected, getSocketState, getOverlayBlockHash | | Scripts & registry state | setScripts, getScript, addScript, getScriptNames, setRegistryState, getRegistryState, clearRegistryState | | Accounts & pending TX | loadTransaction, newAccounts, newAccount, myAccounts, addAccount, removeAccount, clearAccounts, numPendingTx, getPendingTx, waitPendingTx | | Send / subscribe | signAndSendTransaction, signAndSendTransactionWaitResult, subscribeToTransaction, waitForResult, getSeq, getSeqClient, sendTransactionSocket, sendTransaction, backoff | | Signing & preparation | signTransaction, keygen, getPubKey, prepareAndSignTransaction, prepareTransaction, prepareAndRead | | Registry & objects | objectInfo, getRegistry, getUserRegistry, createRegistry, createUserRegistry, getRegistryDomain, getSuperclassInfo, getRegistryDomainEntry, getRegistryEntry, getRegistryEntryLOID, getRegistryEntryObj | | Utilities | base58tohex, uint8hex, hex2uint8, tryJSONparse, sleep, errStr |

TypeScript projects get declarations from types/sagachain-lib.d.ts (run npm run build:types after changing the JS API).

CLI: saga-cli.js

Thin wrapper around the library for submitting scripts and inspecting transactions.

Run from the published package (after npm install @sagachain/client):

npx sagachain-cli [options]
# or
node node_modules/@sagachain/client/saga-cli.js [options]

When developing inside this repo (scripts/):

npm run cli -- [options]
# or
node saga-cli.js [options]

Loads .env via dotenv/config.

Options

| Flag | Env default | Description | |------|-------------|-------------| | --API | API or VITE_API | WebSocket/API base URL (required) | | --account | ACCOUNT | Account (pub key / identifier used by the chain) | | --privKey | PRIV_KEY | Private key (hex or base58) | | --script | — | Path to script file, or - for stdin (also accepts first positional argv as script path) | | --out | — | Write JSON result to file; default - (stdout only) | | --keygen | — | Generate a new keypair and print keys | | --getTx <txId58> | — | Fetch result for a transaction id | | --waitTx <txId58> | — | Subscribe then wait for result | | --waitResult | true | After submit, wait for and print result | | --help | — | Show help |

For read-only calls, saga-cli.js sets isRead when the parsed args include truthy local or read (e.g. you can pass --local / --read through to the underlying signAndSendTransaction vars object—see saga-cli.js).

Positional script path and --script are equivalent to passing the saga script body source.

Example:

API=wss://example/ws PRIV_KEY=... ACCOUNT=... sagachain-cli ./my-script.py
# or (installed dependency path)
API=wss://example/ws PRIV_KEY=... ACCOUNT=... node node_modules/@sagachain/client/saga-cli.js ./my-script.py

When hacking in-repo, use node saga-cli.js ... from scripts/.

CLI: saga-run.js

Batch / test runner (multiple --script, --simulate, account batches, etc.). Same .env pattern.

Installed package:

npx sagachain-run --help
node node_modules/@sagachain/client/saga-run.js --help

This repo (scripts/):

npm run run -- --help
node saga-run.js --help

Uses API from --API or process.env.API, and PRIV_KEY from --privKey or process.env.PRIV_KEY (or generates a key). See --help for full flags (--script, --simulate, --sign, --accounts, …).

Environment

Library (sagachain-lib.js)

| Variable | Where | Purpose | |----------|--------|---------| | VITE_API | import.meta.env (e.g. Vite) | Used when API is not already set (checked before Node process.env) | | API | process.env (Node) | Used when API is not already set and import.meta.env.VITE_API is unset | | VITE_API | process.env (Node) | Fallback after API, matches CLI behavior |

saga-cli.js (via .env or shell)

| Variable | Purpose | |----------|---------| | API | WebSocket/API URL | | VITE_API | Fallback if API is unset (matches CLI default resolution) | | ACCOUNT | Default account | | PRIV_KEY | Default private key |

Other scripts in scripts/ (optional)

These tools use additional env vars (not required for the core library or saga-cli):

| Variables | Used by | |-----------|---------| | COINBASE_API, COINBASE_CODES, RATES_PRIV_KEY, RATES_SCRIPT, SET_RATES_SCRIPT, RATES_DELAY | rates.mjs, rates-coinbase.mjs | | RATES_OBJ_SCRIPT, MAX_RETRIES, YEARS, INDICES_INTERVAL | data-feeds.mjs | | BEA_API_KEY, BLS_API_KEY | us-economy-indices.mjs |

Python helpers

The published package includes the py/ directory (scripts consumed by the library in Node). Paths are not imported as JavaScript modules.

License

MIT (see package.json).