drjones/casino
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ledger): add append-only double-entry engine

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
drjones
2026-08-05 03:23:49 +00:00
parent 8fccbb2a9a
commit 8045e37c16
7 changed files with 756 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docker-compose.yml Normal file
View File

@@ -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:

10
go.mod
View File

@@ -1,3 +1,13 @@
module github.com/drjones/quantum-arcade module github.com/drjones/quantum-arcade
go 1.26.5 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
)

26
go.sum Normal file
View File

@@ -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=

96
migrations/0001_ledger.sql Normal file
View File

@@ -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);

247
pkg/ledger/ledger.go Normal file
View File

@@ -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
}

229
pkg/ledger/ledger_test.go Normal file
View File

@@ -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)
}
}

117
pkg/ledger/property_test.go Normal file
View File

@@ -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)
}
}