From 8045e37c166b6cc69e03874c7a7fd325b5b40965 Mon Sep 17 00:00:00 2001 From: drjones Date: Wed, 5 Aug 2026 03:23:49 +0000 Subject: [PATCH] feat(ledger): add append-only double-entry engine The Lightning bridge is modelled as the boundary with the outside world and is the one account permitted to go negative; its negative balance is exactly what is owed to players inside the system. All other accounts are floored at zero by both the application and a database trigger. Co-Authored-By: Claude Opus 5 --- docker-compose.yml | 31 +++++ go.mod | 10 ++ go.sum | 26 ++++ migrations/0001_ledger.sql | 96 ++++++++++++++ pkg/ledger/ledger.go | 247 ++++++++++++++++++++++++++++++++++++ pkg/ledger/ledger_test.go | 229 +++++++++++++++++++++++++++++++++ pkg/ledger/property_test.go | 117 +++++++++++++++++ 7 files changed, 756 insertions(+) create mode 100644 docker-compose.yml create mode 100644 go.sum create mode 100644 migrations/0001_ledger.sql create mode 100644 pkg/ledger/ledger.go create mode 100644 pkg/ledger/ledger_test.go create mode 100644 pkg/ledger/property_test.go diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..ca1d427 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,31 @@ +services: + postgres: + image: postgres:16-alpine + environment: + POSTGRES_USER: arcade + POSTGRES_PASSWORD: arcade_dev + POSTGRES_DB: arcade + ports: ["5432:5432"] + volumes: + - pgdata:/var/lib/postgresql/data + - ./migrations:/docker-entrypoint-initdb.d:ro + healthcheck: + test: ["CMD-SHELL", "pg_isready -U arcade"] + interval: 2s + timeout: 3s + retries: 20 + + redis: + image: redis:7-alpine + ports: ["6379:6379"] + volumes: + - redisdata:/data + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 2s + timeout: 3s + retries: 20 + +volumes: + pgdata: + redisdata: diff --git a/go.mod b/go.mod index 21675ac..e665bc3 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,13 @@ module github.com/drjones/quantum-arcade go 1.26.5 + +require github.com/jackc/pgx/v5 v5.10.0 + +require ( + github.com/jackc/pgpassfile v1.0.0 // indirect + github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect + github.com/jackc/puddle/v2 v2.2.2 // indirect + golang.org/x/sync v0.17.0 // indirect + golang.org/x/text v0.29.0 // indirect +) diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..c0e505b --- /dev/null +++ b/go.sum @@ -0,0 +1,26 @@ +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM= +github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg= +github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo= +github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM= +github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0= +github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4= +github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo= +github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= +github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= +golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug= +golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI= +golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk= +golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/migrations/0001_ledger.sql b/migrations/0001_ledger.sql new file mode 100644 index 0000000..425e5e0 --- /dev/null +++ b/migrations/0001_ledger.sql @@ -0,0 +1,96 @@ +-- Quantum Arcade ledger: append-only double-entry accounting. +-- +-- Amounts are millisatoshis stored as BIGINT. No UPDATE or DELETE is ever +-- issued against these tables; corrections are compensating transactions. +-- The constraints below restate the application's invariants so that a bug in +-- the Go layer cannot corrupt the books. + +CREATE TYPE account_kind AS ENUM ('player', 'house', 'lightning_bridge'); + +CREATE TABLE accounts ( + id BIGSERIAL PRIMARY KEY, + kind account_kind NOT NULL, + -- Player accounts key on the ed25519 public key; system accounts use a + -- stable name. Exactly one of these is set. + pubkey BYTEA UNIQUE, + name TEXT UNIQUE, + nickname TEXT, + -- The Lightning bridge is the boundary with the outside world: its balance + -- goes negative by exactly the amount owed to players inside the system. + -- Every other account is strictly non-negative. + allow_negative BOOLEAN NOT NULL DEFAULT false, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + CONSTRAINT account_identity CHECK ( + (kind = 'player' AND pubkey IS NOT NULL AND name IS NULL) OR + (kind <> 'player' AND pubkey IS NULL AND name IS NOT NULL) + ) +); + +CREATE TABLE transactions ( + id BIGSERIAL PRIMARY KEY, + kind TEXT NOT NULL, -- 'bet', 'payout', 'deposit', ... + round_id BIGINT, -- NULL for non-game transactions + created_at TIMESTAMPTZ NOT NULL DEFAULT now() +); + +CREATE TABLE postings ( + id BIGSERIAL PRIMARY KEY, + transaction_id BIGINT NOT NULL REFERENCES transactions(id), + account_id BIGINT NOT NULL REFERENCES accounts(id), + -- Positive credits the account, negative debits it. + amount_msat BIGINT NOT NULL, + balance_before BIGINT NOT NULL, + balance_after BIGINT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + CONSTRAINT amount_nonzero CHECK (amount_msat <> 0), + CONSTRAINT balance_arithmetic CHECK (balance_after = balance_before + amount_msat) +); + +-- A CHECK constraint cannot consult another table, so the non-negative rule is +-- a trigger. It is the last line of defence behind the application's own check. +CREATE OR REPLACE FUNCTION enforce_balance_floor() RETURNS TRIGGER AS $$ +DECLARE + permitted BOOLEAN; +BEGIN + SELECT allow_negative INTO permitted FROM accounts WHERE id = NEW.account_id; + IF NOT permitted AND NEW.balance_after < 0 THEN + RAISE EXCEPTION 'account % may not go negative (balance would be %)', + NEW.account_id, NEW.balance_after; + END IF; + RETURN NEW; +END; +$$ LANGUAGE plpgsql; + +CREATE TRIGGER postings_balance_floor + BEFORE INSERT ON postings + FOR EACH ROW EXECUTE FUNCTION enforce_balance_floor(); + +CREATE INDEX postings_account_idx ON postings (account_id, id DESC); +CREATE INDEX postings_transaction_idx ON postings (transaction_id); +CREATE INDEX transactions_round_idx ON transactions (round_id) WHERE round_id IS NOT NULL; + +-- Current balance is the most recent posting's balance_after. +CREATE VIEW account_balances AS +SELECT DISTINCT ON (account_id) + account_id, balance_after AS balance_msat +FROM postings +ORDER BY account_id, id DESC; + +-- Enforce append-only at the database level, not just by convention. +CREATE OR REPLACE FUNCTION reject_mutation() RETURNS TRIGGER AS $$ +BEGIN + RAISE EXCEPTION 'ledger tables are append-only'; +END; +$$ LANGUAGE plpgsql; + +CREATE TRIGGER postings_append_only + BEFORE UPDATE OR DELETE ON postings + FOR EACH ROW EXECUTE FUNCTION reject_mutation(); + +CREATE TRIGGER transactions_append_only + BEFORE UPDATE OR DELETE ON transactions + FOR EACH ROW EXECUTE FUNCTION reject_mutation(); + +INSERT INTO accounts (kind, name, allow_negative) VALUES + ('house', 'house_pot', false), + ('lightning_bridge', 'lightning_bridge', true); diff --git a/pkg/ledger/ledger.go b/pkg/ledger/ledger.go new file mode 100644 index 0000000..75f826c --- /dev/null +++ b/pkg/ledger/ledger.go @@ -0,0 +1,247 @@ +// Package ledger implements append-only double-entry accounting. +// +// Invariants, enforced here and again by database constraints and triggers: +// - every transaction's postings sum to exactly zero +// - no account balance may go negative +// - rows are never updated or deleted; corrections are compensating entries +// +// Every balance change is explained by a posting that records what happened, +// when, which round it belonged to, and the balance either side of it. +package ledger + +import ( + "context" + "errors" + "fmt" + "sort" + "time" + + "github.com/jackc/pgx/v5" + "github.com/jackc/pgx/v5/pgxpool" +) + +var ( + ErrUnbalanced = errors.New("ledger: postings do not sum to zero") + ErrInsufficientFunds = errors.New("ledger: insufficient funds") + ErrEmptyTransaction = errors.New("ledger: transaction has no postings") + ErrNonPositiveAmount = errors.New("ledger: amount must be positive") +) + +// Posting is a single leg of a transaction. Positive credits, negative debits. +type Posting struct { + AccountID int64 + AmountMsat int64 +} + +// Entry is a posting as seen from one account's history. +type Entry struct { + TransactionID int64 + Kind string + RoundID *int64 + AmountMsat int64 + BalanceBefore int64 + BalanceAfter int64 + CreatedAt time.Time +} + +type Ledger struct{ pool *pgxpool.Pool } + +func New(pool *pgxpool.Pool) *Ledger { return &Ledger{pool: pool} } + +// Post writes one balanced transaction atomically. +// +// Accounts are locked in ascending id order so that concurrent transactions +// touching the same accounts cannot deadlock, and so a balance read cannot be +// stale by the time the posting is written. +func (l *Ledger) Post(ctx context.Context, kind string, roundID *int64, postings []Posting) (int64, error) { + if len(postings) == 0 { + return 0, ErrEmptyTransaction + } + var sum int64 + for _, p := range postings { + sum += p.AmountMsat + } + if sum != 0 { + return 0, fmt.Errorf("%w: sum is %d", ErrUnbalanced, sum) + } + + tx, err := l.pool.Begin(ctx) + if err != nil { + return 0, err + } + defer tx.Rollback(ctx) + + var txID int64 + if err := tx.QueryRow(ctx, + `INSERT INTO transactions (kind, round_id) VALUES ($1, $2) RETURNING id`, + kind, roundID).Scan(&txID); err != nil { + return 0, err + } + + ordered := append([]Posting(nil), postings...) + sort.Slice(ordered, func(i, j int) bool { + return ordered[i].AccountID < ordered[j].AccountID + }) + + for _, p := range ordered { + // Lock the account row first, then read its latest balance. Taking the + // lock before the read is what serializes concurrent spends. + var allowNegative bool + if err := tx.QueryRow(ctx, + `SELECT allow_negative FROM accounts WHERE id = $1 FOR UPDATE`, + p.AccountID).Scan(&allowNegative); err != nil { + return 0, fmt.Errorf("locking account %d: %w", p.AccountID, err) + } + + var before int64 + if err := tx.QueryRow(ctx, + `SELECT COALESCE( + (SELECT balance_after FROM postings + WHERE account_id = $1 ORDER BY id DESC LIMIT 1), 0)`, + p.AccountID).Scan(&before); err != nil { + return 0, fmt.Errorf("reading balance of account %d: %w", p.AccountID, err) + } + + after := before + p.AmountMsat + if after < 0 && !allowNegative { + return 0, fmt.Errorf("%w: account %d holds %d, needs %d", + ErrInsufficientFunds, p.AccountID, before, -p.AmountMsat) + } + + if _, err := tx.Exec(ctx, + `INSERT INTO postings + (transaction_id, account_id, amount_msat, balance_before, balance_after) + VALUES ($1, $2, $3, $4, $5)`, + txID, p.AccountID, p.AmountMsat, before, after); err != nil { + return 0, err + } + } + + if err := tx.Commit(ctx); err != nil { + return 0, err + } + return txID, nil +} + +// Transfer moves funds between two accounts. This is the peer-to-peer path. +func (l *Ledger) Transfer(ctx context.Context, from, to int64, amountMsat int64) (int64, error) { + if amountMsat <= 0 { + return 0, ErrNonPositiveAmount + } + return l.Post(ctx, "transfer", nil, []Posting{ + {AccountID: from, AmountMsat: -amountMsat}, + {AccountID: to, AmountMsat: amountMsat}, + }) +} + +// Deposit credits a player from the Lightning bridge account. +func (l *Ledger) Deposit(ctx context.Context, player int64, amountMsat int64) (int64, error) { + if amountMsat <= 0 { + return 0, ErrNonPositiveAmount + } + bridge, err := l.AccountByName(ctx, "lightning_bridge") + if err != nil { + return 0, err + } + return l.Post(ctx, "deposit", nil, []Posting{ + {AccountID: bridge, AmountMsat: -amountMsat}, + {AccountID: player, AmountMsat: amountMsat}, + }) +} + +// Withdraw debits a player back to the Lightning bridge account. +func (l *Ledger) Withdraw(ctx context.Context, player int64, amountMsat int64) (int64, error) { + if amountMsat <= 0 { + return 0, ErrNonPositiveAmount + } + bridge, err := l.AccountByName(ctx, "lightning_bridge") + if err != nil { + return 0, err + } + return l.Post(ctx, "withdraw", nil, []Posting{ + {AccountID: player, AmountMsat: -amountMsat}, + {AccountID: bridge, AmountMsat: amountMsat}, + }) +} + +// Balance returns the account's current balance in millisatoshis. +func (l *Ledger) Balance(ctx context.Context, accountID int64) (int64, error) { + var bal int64 + err := l.pool.QueryRow(ctx, + `SELECT COALESCE( + (SELECT balance_after FROM postings + WHERE account_id = $1 ORDER BY id DESC LIMIT 1), 0)`, + accountID).Scan(&bal) + return bal, err +} + +// History returns an account's postings, newest first. +func (l *Ledger) History(ctx context.Context, accountID int64, limit int) ([]Entry, error) { + rows, err := l.pool.Query(ctx, + `SELECT p.transaction_id, t.kind, t.round_id, + p.amount_msat, p.balance_before, p.balance_after, p.created_at + FROM postings p + JOIN transactions t ON t.id = p.transaction_id + WHERE p.account_id = $1 + ORDER BY p.id DESC + LIMIT $2`, accountID, limit) + if err != nil { + return nil, err + } + defer rows.Close() + + var out []Entry + for rows.Next() { + var e Entry + if err := rows.Scan(&e.TransactionID, &e.Kind, &e.RoundID, + &e.AmountMsat, &e.BalanceBefore, &e.BalanceAfter, &e.CreatedAt); err != nil { + return nil, err + } + out = append(out, e) + } + return out, rows.Err() +} + +// EnsurePlayer returns the account id for a public key, creating it if needed. +func (l *Ledger) EnsurePlayer(ctx context.Context, pubkey []byte) (int64, error) { + var id int64 + err := l.pool.QueryRow(ctx, + `INSERT INTO accounts (kind, pubkey) VALUES ('player', $1) + ON CONFLICT (pubkey) DO UPDATE SET pubkey = EXCLUDED.pubkey + RETURNING id`, pubkey).Scan(&id) + return id, err +} + +// AccountByName resolves a system account such as "house_pot". +func (l *Ledger) AccountByName(ctx context.Context, name string) (int64, error) { + var id int64 + err := l.pool.QueryRow(ctx, + `SELECT id FROM accounts WHERE name = $1`, name).Scan(&id) + if errors.Is(err, pgx.ErrNoRows) { + return 0, fmt.Errorf("ledger: no account named %q", name) + } + return id, err +} + +// TotalIssued is the value held inside the system by players and the house — +// every account except the external Lightning bridge. It changes only when +// funds genuinely enter or leave, never through internal play. +func (l *Ledger) TotalIssued(ctx context.Context) (int64, error) { + var total int64 + err := l.pool.QueryRow(ctx, + `SELECT COALESCE(SUM(b.balance_msat), 0) + FROM account_balances b + JOIN accounts a ON a.id = b.account_id + WHERE NOT a.allow_negative`).Scan(&total) + return total, err +} + +// ConservationCheck sums every account including the bridge. Because each +// transaction sums to zero, this must always be exactly zero. A non-zero +// result means the books are corrupt, and is the top-level audit alarm. +func (l *Ledger) ConservationCheck(ctx context.Context) (int64, error) { + var total int64 + err := l.pool.QueryRow(ctx, + `SELECT COALESCE(SUM(balance_msat), 0) FROM account_balances`).Scan(&total) + return total, err +} diff --git a/pkg/ledger/ledger_test.go b/pkg/ledger/ledger_test.go new file mode 100644 index 0000000..6eaa83d --- /dev/null +++ b/pkg/ledger/ledger_test.go @@ -0,0 +1,229 @@ +package ledger_test + +import ( + "context" + "errors" + "fmt" + "math/rand" + "os" + "sync" + "testing" + "time" + + "github.com/drjones/quantum-arcade/pkg/ledger" + "github.com/jackc/pgx/v5/pgxpool" +) + +func testPool(t *testing.T) *pgxpool.Pool { + t.Helper() + dsn := os.Getenv("ARCADE_TEST_DSN") + if dsn == "" { + dsn = "postgres://arcade:arcade_dev@localhost:5432/arcade" + } + pool, err := pgxpool.New(context.Background(), dsn) + if err != nil { + t.Skipf("no database available: %v", err) + } + if err := pool.Ping(context.Background()); err != nil { + t.Skipf("no database available: %v", err) + } + return pool +} + +// runID is fresh for each execution of the test binary. The ledger is +// append-only and never truncated, so accounts must not be shared between runs +// or balances would accumulate across them. +var runID = fmt.Sprintf("%d-%d", time.Now().UnixNano(), rand.Int63()) + +// uniqueKey produces an account key unique to this test and this run. +func uniqueKey(t *testing.T, label string) []byte { + t.Helper() + return []byte(fmt.Sprintf("%s-%s-%s", runID, t.Name(), label)) +} + +func TestPostRejectsUnbalanced(t *testing.T) { + l := ledger.New(testPool(t)) + ctx := context.Background() + a, err := l.EnsurePlayer(ctx, uniqueKey(t, "a")) + if err != nil { + t.Fatal(err) + } + b, err := l.EnsurePlayer(ctx, uniqueKey(t, "b")) + if err != nil { + t.Fatal(err) + } + _, err = l.Post(ctx, "test", nil, []ledger.Posting{ + {AccountID: a, AmountMsat: -100}, + {AccountID: b, AmountMsat: 50}, + }) + if !errors.Is(err, ledger.ErrUnbalanced) { + t.Fatalf("got %v, want ErrUnbalanced", err) + } +} + +func TestPostRejectsOverdraft(t *testing.T) { + l := ledger.New(testPool(t)) + ctx := context.Background() + a, _ := l.EnsurePlayer(ctx, uniqueKey(t, "a")) + b, _ := l.EnsurePlayer(ctx, uniqueKey(t, "b")) + _, err := l.Post(ctx, "test", nil, []ledger.Posting{ + {AccountID: a, AmountMsat: -1_000_000}, + {AccountID: b, AmountMsat: 1_000_000}, + }) + if !errors.Is(err, ledger.ErrInsufficientFunds) { + t.Fatalf("got %v, want ErrInsufficientFunds", err) + } +} + +func TestRejectedTransactionLeavesNoTrace(t *testing.T) { + l := ledger.New(testPool(t)) + ctx := context.Background() + a, _ := l.EnsurePlayer(ctx, uniqueKey(t, "a")) + b, _ := l.EnsurePlayer(ctx, uniqueKey(t, "b")) + + before, err := l.Balance(ctx, a) + if err != nil { + t.Fatal(err) + } + _, _ = l.Post(ctx, "test", nil, []ledger.Posting{ + {AccountID: a, AmountMsat: -500}, + {AccountID: b, AmountMsat: 500}, + }) + after, err := l.Balance(ctx, a) + if err != nil { + t.Fatal(err) + } + if before != after { + t.Fatalf("failed transaction changed balance: %d -> %d", before, after) + } +} + +func TestConservationOfValue(t *testing.T) { + l := ledger.New(testPool(t)) + ctx := context.Background() + bridge, err := l.AccountByName(ctx, "lightning_bridge") + if err != nil { + t.Fatal(err) + } + p, _ := l.EnsurePlayer(ctx, uniqueKey(t, "player")) + + before, err := l.TotalIssued(ctx) + if err != nil { + t.Fatal(err) + } + if _, err := l.Deposit(ctx, p, 5000); err != nil { + t.Fatal(err) + } + if _, err := l.Withdraw(ctx, p, 5000); err != nil { + t.Fatal(err) + } + after, err := l.TotalIssued(ctx) + if err != nil { + t.Fatal(err) + } + if before != after { + t.Fatalf("total value changed: %d -> %d", before, after) + } + _ = bridge +} + +func TestBalanceTracksPostings(t *testing.T) { + l := ledger.New(testPool(t)) + ctx := context.Background() + p, _ := l.EnsurePlayer(ctx, uniqueKey(t, "p")) + + if _, err := l.Deposit(ctx, p, 12_345); err != nil { + t.Fatal(err) + } + bal, err := l.Balance(ctx, p) + if err != nil { + t.Fatal(err) + } + if bal != 12_345 { + t.Fatalf("balance = %d, want 12345", bal) + } +} + +// Two concurrent spends of the same funds must not both succeed. The account +// row lock is what prevents a double-spend under load. +func TestConcurrentSpendsCannotOverdraw(t *testing.T) { + l := ledger.New(testPool(t)) + ctx := context.Background() + from, _ := l.EnsurePlayer(ctx, uniqueKey(t, "from")) + to, _ := l.EnsurePlayer(ctx, uniqueKey(t, "to")) + + if _, err := l.Deposit(ctx, from, 1000); err != nil { + t.Fatal(err) + } + + const workers = 8 + var wg sync.WaitGroup + succeeded := make([]bool, workers) + for i := 0; i < workers; i++ { + wg.Add(1) + go func(i int) { + defer wg.Done() + _, err := l.Transfer(ctx, from, to, 1000) + succeeded[i] = err == nil + }(i) + } + wg.Wait() + + wins := 0 + for _, ok := range succeeded { + if ok { + wins++ + } + } + if wins != 1 { + t.Fatalf("%d concurrent spends of the same 1000 msat succeeded, want 1", wins) + } + bal, _ := l.Balance(ctx, from) + if bal != 0 { + t.Fatalf("source balance = %d, want 0", bal) + } +} + +func TestAppendOnlyEnforcedByDatabase(t *testing.T) { + pool := testPool(t) + l := ledger.New(pool) + ctx := context.Background() + p, _ := l.EnsurePlayer(ctx, uniqueKey(t, "p")) + if _, err := l.Deposit(ctx, p, 100); err != nil { + t.Fatal(err) + } + _, err := pool.Exec(ctx, `UPDATE postings SET amount_msat = 999 WHERE account_id = $1`, p) + if err == nil { + t.Fatal("UPDATE on postings succeeded; append-only trigger is not working") + } + _, err = pool.Exec(ctx, `DELETE FROM postings WHERE account_id = $1`, p) + if err == nil { + t.Fatal("DELETE on postings succeeded; append-only trigger is not working") + } +} + +func TestHistoryExplainsEveryChange(t *testing.T) { + l := ledger.New(testPool(t)) + ctx := context.Background() + p, _ := l.EnsurePlayer(ctx, uniqueKey(t, "p")) + if _, err := l.Deposit(ctx, p, 800); err != nil { + t.Fatal(err) + } + if _, err := l.Withdraw(ctx, p, 300); err != nil { + t.Fatal(err) + } + entries, err := l.History(ctx, p, 10) + if err != nil { + t.Fatal(err) + } + if len(entries) != 2 { + t.Fatalf("got %d history entries, want 2", len(entries)) + } + // History is newest-first. + if entries[0].Kind != "withdraw" || entries[0].AmountMsat != -300 { + t.Fatalf("unexpected newest entry: %+v", entries[0]) + } + if entries[0].BalanceAfter != 500 { + t.Fatalf("balance after withdraw = %d, want 500", entries[0].BalanceAfter) + } +} diff --git a/pkg/ledger/property_test.go b/pkg/ledger/property_test.go new file mode 100644 index 0000000..938557b --- /dev/null +++ b/pkg/ledger/property_test.go @@ -0,0 +1,117 @@ +package ledger_test + +import ( + "context" + "errors" + "math/rand" + "testing" + + "github.com/drjones/quantum-arcade/pkg/ledger" +) + +// Across a long run of random transfers, bets, and payouts, total value must +// never change and no player balance may go negative. This is the property that +// makes end-of-night settlement trustworthy. +func TestRandomActivityConservesValue(t *testing.T) { + l := ledger.New(testPool(t)) + ctx := context.Background() + + house, err := l.AccountByName(ctx, "house_pot") + if err != nil { + t.Fatal(err) + } + + const players = 8 + ids := make([]int64, players) + for i := range ids { + id, err := l.EnsurePlayer(ctx, uniqueKey(t, string(rune('a'+i)))) + if err != nil { + t.Fatal(err) + } + ids[i] = id + if _, err := l.Deposit(ctx, id, 100_000); err != nil { + t.Fatal(err) + } + } + + before, err := l.TotalIssued(ctx) + if err != nil { + t.Fatal(err) + } + + rng := rand.New(rand.NewSource(1)) + roundID := int64(0) + for i := 0; i < 400; i++ { + amt := int64(rng.Intn(5000) + 1) + player := ids[rng.Intn(players)] + + var err error + switch rng.Intn(3) { + case 0: // peer transfer + other := ids[rng.Intn(players)] + if other == player { + continue + } + _, err = l.Transfer(ctx, player, other, amt) + case 1: // bet: player pays the house + roundID++ + r := roundID + _, err = l.Post(ctx, "bet", &r, []ledger.Posting{ + {AccountID: player, AmountMsat: -amt}, + {AccountID: house, AmountMsat: amt}, + }) + case 2: // payout: house pays the player + roundID++ + r := roundID + _, err = l.Post(ctx, "payout", &r, []ledger.Posting{ + {AccountID: house, AmountMsat: -amt}, + {AccountID: player, AmountMsat: amt}, + }) + } + + // Running out of funds is a legitimate outcome; nothing else is. + if err != nil && !errors.Is(err, ledger.ErrInsufficientFunds) { + t.Fatalf("iteration %d: %v", i, err) + } + } + + after, err := l.TotalIssued(ctx) + if err != nil { + t.Fatal(err) + } + if before != after { + t.Fatalf("value not conserved: %d -> %d", before, after) + } + + for _, id := range ids { + bal, err := l.Balance(ctx, id) + if err != nil { + t.Fatal(err) + } + if bal < 0 { + t.Fatalf("account %d went negative: %d", id, bal) + } + } +} + +// Every transaction sums to zero, so the sum across all accounts including the +// external bridge must be exactly zero at all times. +func TestBooksAlwaysBalanceToZero(t *testing.T) { + l := ledger.New(testPool(t)) + ctx := context.Background() + + p, err := l.EnsurePlayer(ctx, uniqueKey(t, "p")) + if err != nil { + t.Fatal(err) + } + if _, err := l.Deposit(ctx, p, 7_777); err != nil { + t.Fatal(err) + } + total, err := l.ConservationCheck(ctx) + if err != nil { + t.Fatal(err) + } + if total != 0 { + t.Fatalf("books do not balance: total across all accounts = %d", total) + } +}