@cogcoin/client@1.2.13 is the reference Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around @cogcoin/indexer. It publishes the reusable client APIs, the SQLite adapter, the managed bitcoind integration, and the first-party cogcoin CLI in one package.
Use Node 22 or newer.
curl -fsSL https://cogcoin.org/install.sh | bash
# or on Windows PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://cogcoin.org/install.ps1 | iex"- Installs and uses a Cogcoin-managed Node.js runtime.
- Updates PATH for future shells so the managed
cogcoincommand stays available. - Installs
@cogcoin/clientinto a Cogcoin-managed global npm prefix. - Starts
cogcoin initautomatically only when the installer is running in an interactive terminal.
- On macOS, Homebrew is only used if it is already installed and bootstrap tools are missing.
- If the installer is noninteractive, it finishes by printing one exact
cogcoin initfollow-up command. - If you set
COGCOIN_SKIP_INIT=1, the installer skipscogcoin initand prints the exact manual command to run later. - If macOS Command Line Tools are still installing, the installer either waits and retries automatically or prints the exact resume command.
cogcoin address # Send 0.0015 BTC to address
cogcoin register <domainname> # 6+ character domain for 0.001 BTC
cogcoin anchor <domainname> # You can leave a founding message permanently on Bitcoin!
cogcoin mine setup
cogcoin mine # Use remaining ~0.0005 BTC for mining tx, ~1000 sats per entry (0.00001 BTC) ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
▄▀ ▀▄
█ ▄▀▀▀▀▀▀▀▀▀▀▀▀▀▀▄ █ Welcome to...
█ █ █ █
█ █ █ █ █ █ █ █████ █████ █████ █████ █████ ██ ███ ██
█ █ █ █ █ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██
█ █ ▄█ █ █ ██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██
█ █ ▄ ▄ █ █ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
█ █ ▀▀▀▀ █ █ █████ █████ █████ █████ █████ ██ ██ ████
█ ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀ █
█ █ ┏┳┓╻┏┓╻┏━╸ ╻ ╻╻╺┳╸╻ ╻ ╻ ╻┏━┓┏━┓╺┳┓┏━┓
█ █ ┃┃┃┃┃┗┫┣╸ ┃╻┃┃ ┃ ┣━┫ ┃╻┃┃ ┃┣┳┛ ┃┃┗━┓
█ ▄▄ ▄▄▄▄▄▄ █ ╹ ╹╹╹ ╹┗━╸ ┗┻┛╹ ╹ ╹ ╹ ┗┻┛┗━┛╹┗╸╺┻┛┗━┛
█ █
▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀ We are so happy to have you here!
█▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█
⛭ Behold, your Cogcoin wallet. ⛭
▐▀▀▀▀▀▀▀▀▚ ╔──────────────────────────────────────────────────────────────────╗
▛▞▀▀▀▀▀▀▀▀▚ │ │
▌▝▀▀▀▀▀▀▀▀▀▌│ Funding address: bc1qsamplewallet0000000000000000000000000 │
▌ ▗▙▙ ▌│ │
▌ ▐ ▌ ▌│ Bitcoin Balance: 0.00150000 BTC │
▌ ▐▀▀▚ ▌│ Cogcoin Balance: 12.50000000 COG │
▌ ▐▄▄▞ ▌│ │
▌ ▘▘ ▌│ mempool.space/address/bc1qsamplewallet0000000000000000000000000 |
▝▀▀▀▀▀▀▀▀▀▀▘╚──────────────────────────────────────────────────────────────────╝
Anchored Domains
⌂ cogdemo
Unanchored Domains
--- No unanchored domains --- _____ _____
( ___ ) 12.500 COG ⛭ C O G C O I N ⛭ 150000 SAT ( ___ )
| |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| |
| | | |
| | | |
| | 945516 945515 945514 945513 945512| |
| |_|"""""| _|"""""|_|"""""|_|"""""|_|"""""|_|"""""| |
| |"`-0-0-' "`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-'"`-0-0-| |
| | ~10 min | |
| | | |
| | | |
|___|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|___|
(_____) Waiting for indexer (_____)
[░░░░░░░░░░░░░░░░████] Mining is waiting for Bitcoin Core and the indexer to align.
Required words: OWNER, OLYMPIC, ERODE, DESK, DIFFER
@cogdemo: By the desk, the owner observed that Olympic lettering could erode over time, though experts differ.- Website: cogcoin.org
- Whitepaper: cogcoin.org/whitepaper.md
- Source: github.com/cogcoin/client
- Bitcoin package: npmjs.com/package/@cogcoin/bitcoin
- Genesis package: npmjs.com/package/@cogcoin/genesis
- Indexer package: npmjs.com/package/@cogcoin/indexer
- Scoring package: npmjs.com/package/@cogcoin/scoring
The published package depends on:
@cogcoin/bitcoin@30.2.0@cogcoin/genesis@1.0.0@cogcoin/indexer@1.0.2@cogcoin/scoring@1.0.0@scure/base@^2.0.0@scure/bip32@^2.0.1@scure/bip39@^2.0.1better-sqlite3@12.8.0hash-wasm@^4.12.0zeromq@6.5.0
@cogcoin/vectors@1.0.1 is kept as a repository development dependency for conformance tests and is not part of the published runtime dependency surface.
@cogcoin/client@1.2.13 keeps foreground mining runtime status fresh with explicit process/run heartbeats while mining is blocked inside a cycle, separates coherent mining lease tips from the daemon's latest indexed tip in diagnostics, and clears stale waiting-indexer or waiting-bitcoin-network status once live service truth is healthy.
@cogcoin/client@1.2.12 makes cogcoin repair resume managed indexer background follow after restarting the daemon, gives that resume path a longer startup window for mainnet nodes, and prevents late daemon IPC responses from crashing on closed client sockets. Background-follow recovery errors now point users to cogcoin status and the managed indexer daemon log for the underlying cause.
@cogcoin/client@1.2.11 makes cogcoin mine refuse to start when the live managed indexer daemon is running an older binary than the current CLI. The command now exits with a clear next step to run cogcoin repair, so mining does not silently trust stale daemon readiness or publishing state after a CLI update.
@cogcoin/client@1.2.10 keeps mining runtime status fresh while cogcoin mine is waiting for managed indexer preflight. Preflight now writes foreground mining snapshots before and during indexer polling, records stopped/error snapshots for managed-indexer recovery failures, and preserves useful prior mining context for diagnostics. Passive cogcoin status also shows the managed indexer daemon binary version and flags daemon versions older than the CLI so upgrade/recycle drift is visible.
@cogcoin/client@1.2.9 marks stale foreground mining runtime status files as unhealthy in passive cogcoin status and writes a fail-safe stopped mining snapshot when foreground mining exits because the managed indexer background follow could not recover.
@cogcoin/client@1.2.8 centralizes mining authorization so cogcoin mine prompt, cogcoin mine prompt list, domains --mineable, candidate generation, and stale-candidate checks all use the same confirmed-state rule. Anchored root domains are mineable when the current wallet script is the confirmed owner, delegate, or designated miner; unanchored domains, subdomains, read-only domains, and domains authorized only for legacy local scripts remain non-mineable.
@cogcoin/client@1.2.7 makes cogcoin repair a deliberate managed-service recycle. Repair now stops the Cogcoin-managed indexer daemon, stops and clears only Cogcoin-managed bitcoind runtime artifacts, restarts bitcoind with the current managed configuration, and restarts the indexer after Core is ready enough. If Bitcoin Core is still loading its block index, repair leaves the indexer stopped so the next cogcoin sync, cogcoin mine, or cogcoin repair can start it after Core finishes warming up.
@cogcoin/client@1.2.6 adds diagnostics for safe mining skips when the mempool competitiveness gate cannot be verified. Mining still refuses to publish unless the gate can prove the candidate is safe, but runtime status, cogcoin status, cogcoin mine status, mining UI notes, and mining events now include stable reason codes and compact mempool counters for support/debugging.
@cogcoin/client@1.2.5 keeps managed Bitcoin runtime settings in bitcoin.conf instead of duplicating RPC, P2P, wallet, and ZMQ settings on the bitcoind command line. This prevents duplicate pubhashblock and pubrawtx ZMQ registrations. Managed startup, repair, bitcoin status, and status --live also refresh runtime status after successful RPC/ZMQ checks so a stale starting status does not remain after Core is ready.
@cogcoin/client@1.2.4 treats a live managed Bitcoin Core process returning startup -28 Loading block index... as a normal starting state. cogcoin mine waits instead of repeatedly restarting the process, and cogcoin repair prints progress during long checks. If repair restarts a stale managed bitcoind to add raw transaction ZMQ support and Core is still loading, repair exits with a clear note to wait and rerun cogcoin status or cogcoin mine.
@cogcoin/client@1.2.0 updates the runtime indexer to @cogcoin/indexer@1.0.2. Existing wallet state, mining configuration, Bitcoin Core data, and secrets remain compatible and are not reset.
On the first managed indexer start after upgrading, cogcoin sync, cogcoin mine, cogcoin follow, and related managed-indexer commands automatically clear and replay the local Cogcoin indexer SQLite projection once. This is required so the local index contains the complete explorer history and winner bip39WordIndices produced by @cogcoin/indexer@1.0.2.
Supabase mirror operators should let the local client replay and catch up first, then run:
cogcoin-supabase reset --yes --recreate-schemaOld snapshots may deserialize successfully but can lack historical explorer rows and required winner bip39WordIndices for blocks indexed before @cogcoin/indexer@1.0.2, so they should not be used as the source for a complete Supabase reset.
Root package:
openClient(options)createClientStoreAdapter(store)
SQLite subpath:
@cogcoin/client/sqliteopenSqliteStore(options)migrateSqliteStore(database)
Managed node subpath:
@cogcoin/client/bitcoindopenManagedBitcoindClient(options)
The installed cogcoin command covers the first-party local wallet and node workflow:
- update commands such as
updateto compare the current CLI version with the latest npm release and install it - wallet lifecycle commands such as
init,reset,wallet show-mnemonic, andrepair - sync and service commands such as
status,sync,follow,bitcoin start,bitcoin stop,bitcoin status,indexer start,indexer stop, andindexer status - domain and field commands such as
register,anchor,show,domains,fields,buy,sell, andtransfer - COG and reputation commands such as
send,cog lock,claim,reclaim,rep give, andrep revoke - mining commands such as
mine,mine status,mine log,mine setup,mine prompt, andmine prompt list
cogcoin status is passive by default: it reads local SQLite/runtime status files without prompting for the client password, starting services, or making Bitcoin RPC calls. Use cogcoin status --live when you want the full RPC-backed wallet overview and balance report.
Use cogcoin mine prompt <domain> to set or clear a per-domain mining prompt override for one anchored root domain, and cogcoin mine prompt list to inspect the current per-domain prompt state alongside the global fallback prompt.
Interactive text invocations periodically check the npm registry for newer @cogcoin/client releases and print npm install -g @cogcoin/client when a newer version is available.
Set COGCOIN_DISABLE_UPDATE_CHECK=1 to disable the CLI update notice entirely.
Ordinary sync, follow, and wallet-aware live read flows detach from the managed Bitcoin and indexer services on exit instead of stopping them.
Use the explicit bitcoin ... and indexer ... commands when you want direct service inspection or start/stop control.
For provider-backed local wallets, normal reads, mutations, and mining setup flows load local wallet state on demand whenever the local secret provider is available.
When no wallet exists yet, cogcoin init interactively lets you either create a new wallet or restore an existing one from a 24-word English BIP39 mnemonic, then continues into sync.
To replace an existing wallet with a different mnemonic, run cogcoin reset, choose clear wallet entropy, and then rerun cogcoin init.
The built-in SQLite adapter persists opaque indexer bytes rather than protocol tables:
- serialized
IndexerState - serialized
BlockRecord - current tip metadata
- periodic checkpoints
This keeps correctness tied to @cogcoin/indexer rather than duplicating protocol state in SQL.
The built-in managed-node integration:
- resolves Bitcoin Core binaries through
@cogcoin/bitcoin - uses RPC for durable reads and ZMQ
hashblocknotifications for tip following - launches a local full node with cookie auth
- defaults to an assumeutxo-first mainnet bootstrap using
https://snapshots.cogcoin.org/utxo-910000.dat - opportunistically loads the public getblock range family from
https://snapshots.cogcoin.org/getblock-manifest.jsonplus immutablegetblock-<first>-<last>.datbands to accelerate post-910000Bitcoin Core catch-up - composes the existing SQLite-backed client rather than replacing it
If dataDir is omitted, the managed node defaults to:
- macOS:
~/Library/Application Support/Cogcoin/bitcoin - Linux:
~/.cogcoin/bitcoin - Windows:
%APPDATA%\\Cogcoin\\bitcoin
On a fresh mainnet managed sync, syncToTip() or startFollowingTip():
- downloads the pinned Cogcoin UTXO snapshot with resume support
- validates its known size and SHA-256
- loads it with Bitcoin Core assumeutxo
- opportunistically checks for the next published 500-block getblock band at each post-snapshot boundary
- downloads, validates, and loads that range into managed Bitcoin Core when available
- syncs Cogcoin through that range, deletes the consumed local band cache, and repeats for the next boundary
- falls back to ordinary Bitcoin sync and Cogcoin replay once no further published range exists
The public getblock range provenance is tracked in the companion scraper repository:
That repo documents how getblock-manifest.json and immutable files such as getblock-910001-910500.dat and getblock-910501-911000.dat are assembled from bitcoin-cli getblockhash plus bitcoin-cli getblock <hash> 0, including the blk-style file layout, range manifest format, durability guarantees, and publish order.
The managed bitcoind client also exposes:
onProgress(event)for structured bootstrap/sync progress updatesprogressOutput: "auto" | "tty" | "none"for the built-in scroll-train terminal progress UI
At the CLI layer, managed services are persistent until explicitly stopped.
cogcoin bitcoin start starts managed bitcoind, cogcoin bitcoin stop stops managed bitcoind and the paired indexer, cogcoin indexer start starts the managed indexer and auto-starts bitcoind first when needed, and cogcoin indexer stop stops only the indexer.
The default TTY progress renderer ships with the package and uses the bundled scroll, train, and quote assets from dist/art/* and dist/writing_quotes.json.
dist/index.js: public package entrypointdist/index.d.ts: bundled type declarationsdist/cli.js: installedcogcoincommanddist/bitcoind/index.js: managedbitcoindsubpathdist/bitcoind/index.d.ts: managedbitcoinddeclarationsdist/sqlite/index.js: SQLite adapter subpathdist/sqlite/index.d.ts: SQLite adapter declarationsdist/writing_quotes.json: bundled progress UI quote datasetdist/art/*: bundled terminal progress artworkdist/*: compiled ESM implementationREADME.md: package guideLICENSE: MIT license text