store

Overview ¶

Package store is the aggregating factory for the SDK's persistence layer. It wires together the five per-domain stores (utxo, vtxo, transaction, asset, contract) against a SQLite database and exposes them through the types.Store interface so the rest of the SDK can stay backend-agnostic.

Factory ¶

NewStore takes a Config with:

• StoreType — currently only types.SQLStore ("sql") is supported.
• Args (any) — backend-specific arguments, type-asserted by the backend. The SQL backend shipped today expects a `string` datadir used as the SQLite db file's parent. The any-typed slot lets future backends accept whatever shape they need — a Postgres DSN, a pre-opened *sql.DB, a remote endpoint URL — without widening the Config struct.

When StoreType is anything other than types.SQLStore, NewStore returns "unknown store type". When the asserted Args type doesn't match what the SQL backend expects, NewStore returns an error of the form "invalid config args for sqlite store: expected string datadir, got <T>".

SQL stores apply embedded migrations via golang-migrate's iofs source at construction time — the migrations themselves live in store/sql/migration/ and are baked into the binary via embed.FS, so no external migration step is needed at runtime.

Sub-packages ¶

• store/sql (sqlite via database/sql + sqlc) — one *sql.DB shared across every per-domain store, queries generated by sqlc from store/sql/sqlc/query.sql, and migrations driven by golang-migrate. The shared *sql.DB enables ad-hoc SQL access (debugging, reporting) and coordinated cross-table writes within a single transaction.

Per-domain interfaces ¶

Each per-domain store interface lives in the top-level types package — types.UtxoStore, types.VtxoStore, types.TransactionStore, types.AssetStore, types.ContractStore — so backends can implement them independently. The aggregating types.Store returned by NewStore holds one of each plus the Clean / Close lifecycle methods.

Lifecycle ¶

Stores are constructed eagerly inside NewStore. Close closes the shared *sql.DB once — there is no per-domain teardown because every domain store shares the same handle. Clean fan-outs explicitly to per-domain Clean methods, intended for the "wallet reset" code path; it ignores individual errors and proceeds across domains.

Adding a new backend ¶

To plug in a new backend:

1. Implement each types.*Store interface against the new backing store (probably as a new sub-package, mirroring store/sql).
2. Wire its constructors into NewStore behind a new StoreType constant in types/. Type-assert Config.Args to whatever shape the backend needs, returning a clear error on mismatch.
3. If the new backend has its own migration surface (e.g. Postgres), follow the store/sql pattern: keep migration files alongside the package and run them in the constructor with embed.FS.