Append-only points ledger

<?php

namespace App\Loyalty;

use App\Models\LedgerEntry;
use App\Models\Member;
use Illuminate\Support\Facades\DB;
use RuntimeException;

final class PointsLedger
{
    public static function balance(Member $member): int
    {
        return (int) LedgerEntry::where('member_id', $member->id)->latest('id')->value('balance_after');
    }

    /** Positive amount earns, negative spends. Returns the existing entry for a repeated key. */
    public static function post(Member $member, int $amount, string $reason, string $key): LedgerEntry
    {
        return DB::transaction(function () use ($member, $amount, $reason, $key) {
            // Serialises concurrent postings for this member only.
            Member::whereKey($member->id)->lockForUpdate()->first();

            if ($existing = LedgerEntry::where('idempotency_key', $key)->first()) {
                return $existing;
            }

            $balance = self::balance($member) + $amount;

            if ($balance < 0) {
                throw new RuntimeException('Not enough points.');
            }

            return LedgerEntry::create([
                'member_id' => $member->id,
                'amount' => $amount,
                'balance_after' => $balance,
                'reason' => $reason,
                'idempotency_key' => $key,
            ]);
        });
    }
}

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use LogicException;

class LedgerEntry extends Model
{
    public const UPDATED_AT = null; // rows are written once

    protected $guarded = [];

    protected static function booted(): void
    {
        // History is append-only: fix mistakes with a reversing entry instead.
        static::updating(fn () => throw new LogicException('Ledger entries are immutable.'));
        static::deleting(fn () => throw new LogicException('Ledger entries cannot be deleted.'));
    }
}