bitwave-wallet-sdk

README

bitwave-wallet-sdk

A Go toolkit for building on-chain, accounting-aware, agent-first CLIs.

It gives you four things that normally take months to get right, behind a small set of importable packages:

1. Self-custodied EVM wallets (HD / BIP-39, keystore-backed).
2. Non-custodial transaction building — actions become unsigned transactions; the SDK never signs or holds keys unless you ask it to.
3. A pluggable signer + executor seam — sign locally by default, or hand signing/broadcast to a custodian, KMS, or relayer without touching any calling code.
4. Plain-text double-entry accounting that reconciles to on-chain reality — every wallet movement can become a balanced journal entry, readable by hledger / ledger / beancount.

The headline use case: you (or an agent acting for you) move money on-chain, and at the end of the day every unit — native or token — is in a balanced, auditable, exportable ledger.

go get github.com/bitwave-io/bitwave-wallet-sdk

Requires Go 1.25+.

Stability: v0 — the API may change between minor versions until v1.0.0. Pin a tagged release.

---

The model (read this first)

• Your wallet is your identity. wallet.GenerateHD creates a BIP-39 HD wallet; the mnemonic is the only backup. Keystores are plain files on disk (dev-grade) — wire your own Signer for production custody.
• Every action is an unsigned transaction. txbuild packs calldata into a chain.UnsignedTx. Nothing is signed or sent as a side effect.
• Signing and execution are explicit, swappable steps. A signer.Signer turns an unsigned tx into a signed one; an executor.Executor broadcasts it. The defaults are local + JSON-RPC; a custodian swaps in their own.
• Books reconcile regardless of who custodies. The sync bridge turns on-chain transactions into balanced accounting/model entries no matter whether you signed locally or a custodian executed for you.

txbuild.Approve(...) ─▶ chain.UnsignedTx ─▶ signer.Sign ─▶ executor.Execute ─▶ on-chain
                                                                   │
                                                                   ▼
                                                   sync.TransformToEntry ─▶ balanced journal entry

---

Packages

Package	What it is
core	Dependency-light EVM value types: Address, Hash32.
chain	RPC client (balance / nonce / estimate / simulate), UnsignedTx (wallet-ready 0x-hex JSON), Profile (chainId + named contract registry), secp256k1 signing helpers.
wallet	HD (BIP-39/32) keystore: GenerateHD, ImportMnemonic, Save/Load/List/Resolve, network + ERC-20 token metadata, EIP-1559 send orchestration.
txbuild	Generic ERC-20 builders (Approve, Transfer, BalanceOfCalldata, Mint) + Raw for wrapping your own contract methods.
signer	Signer interface + LocalSigner (keystore) default. The one place a key is used.
executor	Executor interface + ChainExecutor (sign + broadcast + wait) default. The custodian hook.
sync	On-chain → journal bridge: turns chain transactions into balanced entries; per-(wallet, network) sync watermarks.

The double-entry accounting layer lives in a separate, zero-dependency module — bitwave-accounting-sdk (model, store, report, format, config) — which this SDK depends on. The sync package bridges on-chain activity into its model.Entry type.

Domain-specific logic (a protocol's contract bindings, its bespoke create calldata, its CLI commands) lives in your application and is built on these primitives — it is intentionally not part of the SDK.

---

The custodian hook

The single most important extension point is the Signer / Executor seam. The default is non-custodial and local:

w, _ := wallet.GenerateHD("treasury")
sgn, _ := signer.NewLocalSigner(w)

ex, _ := executor.Dial(ctx, "https://mainnet.base.org", sgn)
defer ex.Close()

tx, _ := txbuild.Transfer(sgn.Address(), usdc, recipient, amount)
res, _ := ex.Execute(ctx, tx) // signs locally, broadcasts, waits for the receipt

A custodian wraps their own API by implementing executor.Executor — calling code is unchanged:

type custodianExecutor struct { /* endpoint, api key, http client */ }

func (c *custodianExecutor) Execute(ctx context.Context, tx chain.UnsignedTx) (executor.Result, error) {
    // POST the unsigned tx (it marshals to wallet-ready 0x-hex JSON) to your
    // signing+broadcast API, return the resulting tx hash.
}

var _ executor.Executor = (*custodianExecutor)(nil)

See executor/executor_example_test.go for a complete, tested reference.

---

Accounting-aware sync

sync.TransformToEntry turns one on-chain transaction (with its native, token, and internal sub-transfers + gas) into a single balanced model.Entry: the wallet's legs are classified by address, gas becomes an expense posting, and the opaque counterparty rolls up into an uncategorized account you reclassify later. The result balances by construction and round-trips through every plain-text accounting tool.

---

Building your own CLI on this

A downstream CLI imports the packages it needs and adds only its domain layer + flag wiring:

1. wallet for key management.
2. txbuild.Raw (or the generic ERC-20 helpers) to build your protocol's calls.
3. signer + executor to sign and broadcast — local by default, custodian by swap.
4. accounting + sync so every action lands in a balanced, auditable ledger.

The bwx CLI is a full reference consumer built entirely on these packages.

---

License

Mozilla Public License 2.0. You can link this SDK into any software, open or closed; modifications to the SDK's own files must be shared under the MPL.