REST API and database contract

<iframe
  title="Partner Lotto"
  src="https://luckotto.example/embed?partnerId=018f58d2-2802-7000-8000-000000000002&playerUname=DisplayName&playerIdentifier=opaque-public-id"
  style="width:100%;max-width:560px;height:760px;border:0;"
  loading="lazy"
></iframe>

The iframe calls public /api/luckotto endpoints and must never receive an API key or partner-owned pricing settings.

1. Website user creates or rotates a partner API key.
2. The embed calls /api/luckotto/bootstrap to load public display data.
3. Iframe quotes selected hint numbers, creates a deposit address hint, and receives a Bitcoin address.
4. Every confirmed payment to any old or new deposit address becomes eligible for ticket allocation.
5. The scanner allocates the best non-overlapping candidate it finds within the payment amount.
6. Round settlement stores the full weighted draw order and finds the first sold ticket to complete six hits.
7. The monolith exposes public round, ticket, allocation, fee, and payout data.

CREATE TABLE partner_sites (
  id uuid PRIMARY KEY,
  owner_user_id uuid NOT NULL REFERENCES users(id),
  house_edge double precision NOT NULL DEFAULT 0,
  api_key text NOT NULL UNIQUE
);

CREATE TABLE deposit_addresses (
  id uuid PRIMARY KEY,
  partner_site_id uuid NOT NULL REFERENCES partner_sites(id),
  player_identifier text NOT NULL,
  player_uname text,
  hint_numbers integer[] NOT NULL,
  nonce integer NOT NULL,
  deposit_address text NOT NULL UNIQUE,
  deposit_hash_tweak_payload text NOT NULL,
  deposit_hash_tweak_path text NOT NULL,
  UNIQUE (partner_site_id, player_identifier, nonce)
);

CREATE TABLE tickets (
  id uuid PRIMARY KEY,
  payment_id uuid NOT NULL UNIQUE REFERENCES payments(id),
  round_number integer NOT NULL REFERENCES rounds(round_number),
  hint_numbers integer[] NOT NULL,
  numbers integer[] NOT NULL,
  price_sats bigint NOT NULL,
  explicit_fee_sats bigint NOT NULL
);

CREATE INDEX tickets_numbers_gin_idx ON tickets USING gin (numbers);

CREATE TABLE rounds (
  round_number integer PRIMARY KEY,
  closing_block_hash text,
  draw_order integer[],
  winning_ticket_id uuid,
  winning_claim_numbers integer[],
  settled_at timestamptz
);

-- /api/luckotto exposes Luckotto ticket routes over direct queries.
-- POST /api/luckotto/orders/quote returns a suggested weighted claim budget and explicit fee.
-- POST /api/luckotto/orders creates a deposit address hint and returns a valid deposit address.