Expose a payment storage interface with an embedded default #1

New issue

Closed

opened 2026-10-09 11:19:42 +00:00 by thesimplekid · 0 comments

thesimplekid commented

2026-10-09 11:19:42 +00:00

Owner

Problem

Engine::open(directory) currently owns a concrete redb store for intents, receipts, authorizations, capture decisions, pending Cashu operations, and payout journals. This is convenient for the first release, but applications with an existing database cannot choose where payment coordination state lives.

Proposed improvement

Introduce a public storage interface and an Engine construction path that accepts a caller-provided implementation. Keep the current embedded redb implementation and directory-based setup as the default.

Design the interface around atomic domain operations rather than generic reads and writes. In particular, implementations must preserve:

Idempotent intent creation with immutable terms.
Global receipt ownership and atomic receipt/intent completion.
Durable, mutually exclusive claim and reject decisions before network effects.
Ordered and deduplicated authorization observations.
Immutable settlement destinations and quotes, with protection against stale writes.
Payout deduplication and recovery of uncertain outcomes.

Document how an application can coordinate a resource reservation with this interface. Sharing a database does not make a Lightning RPC transactional; durable decisions and recovery are still required. Do not imply that adding a backend automatically enables multiple Engine processes.

Acceptance criteria

Applications can supply a store without Engine opening its own redb database.
The embedded default remains straightforward to use.
A reusable store contract test suite covers concurrency, idempotency, interrupted operations, and restart recovery.
Documentation states transaction, durability, and ownership requirements.
CDK wallet storage remains a separate concern; this issue does not require implementing PostgreSQL or migrating existing data.

This is a post-first-release improvement. The current embedded design is acceptable for the initial release.

## Problem `Engine::open(directory)` currently owns a concrete redb store for intents, receipts, authorizations, capture decisions, pending Cashu operations, and payout journals. This is convenient for the first release, but applications with an existing database cannot choose where payment coordination state lives. ## Proposed improvement Introduce a public storage interface and an Engine construction path that accepts a caller-provided implementation. Keep the current embedded redb implementation and directory-based setup as the default. Design the interface around atomic domain operations rather than generic reads and writes. In particular, implementations must preserve: - Idempotent intent creation with immutable terms. - Global receipt ownership and atomic receipt/intent completion. - Durable, mutually exclusive claim and reject decisions before network effects. - Ordered and deduplicated authorization observations. - Immutable settlement destinations and quotes, with protection against stale writes. - Payout deduplication and recovery of uncertain outcomes. Document how an application can coordinate a resource reservation with this interface. Sharing a database does not make a Lightning RPC transactional; durable decisions and recovery are still required. Do not imply that adding a backend automatically enables multiple Engine processes. ## Acceptance criteria - Applications can supply a store without Engine opening its own redb database. - The embedded default remains straightforward to use. - A reusable store contract test suite covers concurrency, idempotency, interrupted operations, and restart recovery. - Documentation states transaction, durability, and ownership requirements. - CDK wallet storage remains a separate concern; this issue does not require implementing PostgreSQL or migrating existing data. This is a post-first-release improvement. The current embedded design is acceptable for the initial release.

thesimplekid referenced this issue

2026-10-09 11:20:54 +00:00

Pluggable storage, so services on PostgreSQL or with several instances can embed satsettle #6

thesimplekid referenced this issue from a commit

2026-10-09 13:25:04 +00:00

feat: accept atomic payment storage backends

thesimplekid referenced this issue from a pull request that will close it,

2026-10-09 13:25:16 +00:00

feat: accept atomic payment storage backends #17

thesimplekid closed this issue

2026-10-09 14:21:36 +00:00