BigchaindbStore — BigchainDB blockchain database

BigchaindbStore — BigchainDB blockchain database Overview BigchainDB is a blockchain database: data is written as cryptographically signed, immutable transactions over assets. A CREATE transaction registers a new asset (with arbitrary immutable asset.data and mutable metadata); TRANSFER transactions spend prior outputs. Because every transaction is Ed25519-signed and content-addressed by its hash (tx.id), the ledger is append-only and tamper-evident by construction. BigchainDB is not a SQL Dialect, so BigchaindbStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — plus the shared ledger surface (append/get/history/verify/query). Identity: Property | Value | --------- | -------------------- | name | 'bigchaindb' | library | 'bigchaindb-driver'| The store uses two pieces of bigchaindb-driver: a Connection (HTTP transport) and the Transaction factory (builds/signs transactions client-side). Lazy loading — not a hard dependency bigchaindb-driver is not a hard dependency of this package. It is loaded lazily via require() inside connect(), rather than a top-level import. Importing this module therefore does not require the package to be installed — it is only needed when a BigchainDB store is actually connected. When not injected, connect() builds new driver.Connection(url, headers) and uses driver.Transaction as the factory. Injected client BigchaindbStoreOptions accepts a pre-built client (a BigchaindbConnectionLike) and, alongside it, a transaction factory (BigchaindbTransactionFactory). When client is provided, connect() uses it verbatim and takes the transaction factory from options.transaction (or null). This is how the test suite injects a mock connection + mock transaction factory (no package, no network). Connection Build a store from connection options and call connect(). All options are optional, but writing (append) requires a keypair. Option | Type | Purpose | ------------- | ------------------------------- | ----------------------------------------------------------------------------- | url | string | API root. Defaults to 'http://localhost:9984/api/v1/'. | headers | Record<string, string> | Extra headers (e.g. appid/appkey for hosted BigchainDB). | keypair | BigchaindbKeypair | Ed25519 keypair used to sign CREATE transactions in append. Required to write. | client | BigchaindbConnectionLike | A pre-built Connection. When set, the package is not required. | transaction | BigchaindbTransactionFactory | A pre-built Transaction factory (injected in tests alongside client). | Injected-client form Methods Reads/writes wrap failures in a DatabaseError (via DatabaseError.from, prefixing the message with the failing action). Using any method before connect() (or after disconnect()) throws a ConnectionError. Lifecycle Method | Signature | Behavior | ------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client (+ transaction) if provided, otherwise lazy-requires bigchaindb-driver and builds a Connection. Idempotent. Wraps failures in ConnectionError. | disconnect | disconnect(): Promise<void> | Clears the connection, transaction factory, and connected state (no network call — the driver is stateless HTTP). | isConnected | isConnected(): boolean | true only when connected and a connection is present. | getClient | getClient(): BigchaindbConnectionLike | Returns the underlying Connection for operations not wrapped here. Throws ConnectionError if not connected. | Ledger surface Method | Signature | driver call | Behavior | --------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | append | append(table: string, data: Record<string, unknown>): Promise<string> | makeCreateTransaction + signTransaction + postTransactionCommit | Builds, signs, and commits a CREATE transaction whose asset data is { table, ...data } and metadata is { table }. Returns the new tx.id (content hash). Throws DatabaseError (code: 'INVALIDCONNECTION') if no keypair, or (code: 'QUERYERROR') if no transaction factory. | get | get(table: string, id: string): Promise<unknown> | getTransaction | Fetches a transaction by its id. The table argument is ignored (transactions are addressed by id alone). | history | history(table: string, id: string): Promise<unknown> | listTransactions({ assetid: id }) | Lists every transaction (CREATE + subsequent TRANSFERs) for the asset id. Throws DatabaseError (code: 'QUERYERROR') if the connection has no listTransactions. | verify | verify(table: string, id: string): Promise<{ id: string; valid: boolean; transaction: unknown }> | getTransaction | Fetches the signed transaction and reports { id, valid: transaction != null, transaction }. The transaction's Ed25519 signatures + content-hash id are its proof of integrity. | query | query(text: string): Promise<unknown> | searchAssets(text) | Full-text search over asset data. Throws DatabaseError (code: 'QUERYERROR') if the connection has no searchAssets. | Note: append takes a keypair from the store options, not per-call. verify reports validity as "the transaction exists"; it does not re-run the Ed25519 signature check locally. Example Verification status Unit / mock-verified only. The tests in tests/nosql/bigchaindb.test.ts inject a mock connection via BigchaindbStoreOptions.client and a mock transaction factory via transaction, so connect() never loads bigchaindb-driver and no network is touched. What this proves: append calls makeCreateTransaction({ table, ...data }, { table }, [output], publicKey), then signTransaction(created, privateKey), then postTransactionCommit(signed), and returns the committed tx.id. append throws DatabaseError when no keypair is configured. get/verify call getTransaction(id); verify returns { id, valid, transaction } and reports valid: false when the transaction is missing. history calls listTransactions({ assetid }); query calls searchAssets(text). Lifecycle: connecting via injected connection, disconnect(), and ConnectionError from getClient() / reads before connect(). Error handling: connection failures wrapped in DatabaseError. What this does not prove: live execution against a real BigchainDB node, actual Ed25519 signing correctness, or on-chain commit. The call/response shape is verified against the driver's documented contract, but end-to-end execution over the wire has not been exercised here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories