<iframe
  title="Partner Lotto"
  src="https://hookedin.example/embed?partner=partner-slug&playerPublicIdentifier=PUBLIC_PLAYER_ID&playerPrivateIdentifier=PRIVATE_ACCOUNT_ID"
  style="width:100%;max-width:560px;height:760px;border:0;"
  loading="lazy"
  referrerpolicy="strict-origin-when-cross-origin"
></iframe>

`playerPublicIdentifier` is display-safe public ledger attribution. `playerPrivateIdentifier` is used for partner reconciliation and can match the public value when that is acceptable. Neither value is a login token or authorization mechanism. The iframe can render public round information without them, but ticket buying stays disabled until the parent site passes both values.

1. Partner creates a live partner site and public payout address.
2. Partner embeds /embed?partner=PARTNER_SLUG in its own product; buying tickets requires adding playerPublicIdentifier and playerPrivateIdentifier after parent-site login.
3. Iframe loads current round, partner settings, ticket price, house edge, and payout disclosure.
4. Player creates an order; Hookedin allocates a unique deposit address.
5. Scanner records confirmed payment outpoints on the order and recalculates the ticket slip.
6. The order's single slip receives a ticket range in the global shared round sequence.
7. Closing block hash settles the round and selects the winning ticket.
8. Settlement creates a partner_wins row only when the winning ticket is in a sold slip.
9. Admin generates, signs, broadcasts, and refreshes the payout PSBT.

Page files are organized with Next route groups: app/(hookedin) for Hookedin website pages, app/(shared) for pages exposed on both surfaces, and app/(embed) for partner iframe pages. The URL paths below are generated from the same route taxonomy used by chrome, headers, and middleware.

player_ticket_price_sats = ceil(base_ticket_price_sats * (1 + partner_house_edge))
	ticket_count = floor(gross_paid_sats / player_ticket_price_sats)
	jackpot_contribution_sats = ticket_count * base_ticket_price_sats
	partner_balance_delta_sats = gross_paid_sats - jackpot_contribution_sats
	round_jackpot_sats = total_ticket_count * base_ticket_price_sats

The order stores the partner, player, payout address, base ticket price, player ticket price, and whole-percent house edge snapshots. The slip stores the funded assignment. A 0.1 decimal house-edge rate on a 100 sat base ticket means that partner's players pay 110 sats for one ticket.

CREATE TABLE partner_sites (
  id uuid PRIMARY KEY,
  owner_user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  name text NOT NULL,
  display_name text NOT NULL,
	  status text NOT NULL DEFAULT 'draft',
	  theme jsonb NOT NULL DEFAULT '{}'::jsonb,
	  embed_allowed_origins text[] NOT NULL DEFAULT '{}'::text[],
	  house_edge_percent smallint NOT NULL DEFAULT 0,
	  payout_address text NOT NULL,
	  payout_address_network text NOT NULL,
	  CHECK (status IN ('draft', 'live', 'paused')),
	  CHECK (house_edge_percent BETWEEN 0 AND 15)
	);

CREATE UNIQUE INDEX partner_sites_normalized_name_idx
  ON partner_sites ((translate(replace(lower(name), '-', ''), '0134578', 'oleastb')));

CREATE TABLE order_payments (
  id uuid PRIMARY KEY,
  order_id uuid NOT NULL REFERENCES ticket_orders(id) ON DELETE CASCADE,
  txid text NOT NULL,
  vout integer NOT NULL,
  amount_sats bigint NOT NULL,
  block_height bigint NOT NULL,
  block_hash text NOT NULL,
  credited_round_number integer REFERENCES rounds(round_number),
  orphaned_at timestamptz,
  UNIQUE (order_id, txid, vout)
);

CREATE TABLE partner_wins (
  id uuid PRIMARY KEY,
  partner_site_id uuid NOT NULL REFERENCES partner_sites(id) ON DELETE CASCADE,
  round_number integer NOT NULL REFERENCES rounds(round_number),
  slip_id uuid NOT NULL REFERENCES ticket_slips(id),
  winning_ticket_number bigint NOT NULL CHECK (winning_ticket_number >= 0),
  player_public_identifier text,
  player_private_identifier text,
  UNIQUE (partner_site_id, round_number, slip_id)
);

Orders carry partner setting snapshots so later changes do not rewrite existing receipts, payout destinations, or house edge snapshots. Slips stay focused on the ticket assignment. UUID primary keys use UUIDv7, so creation time is derived from the ID instead of a separate creation timestamp column.

state = bytes(closingBlockHash)
repeat HASHES_PER_DIGIT hashes for each configured ticket digit
digit = state as a decimal number mod 10
drawDigits = digit + drawDigits
winningTicket = integer(drawDigits)

Partner metadata, house edge, payout address, and player IDs do not enter the draw. Verification only needs the closing block hash and the round's locked ticket digits. Settlement maps a sold winning ticket to the public slip whose inclusive ticket range contains it. If the ticket is unsold, the house holds that number and no player payout is created.

Settled rounds record the winner algorithm ID, draw digits, and draw calculation digests. The hash work per digit comes from the application environment.

• Dashboard and partner settings routes require a user session.
• Partner settings updates enforce owner_user_id.
• Embedded order creation does not require a Hookedin session, but it must be a same-origin JSON request from the iframe.
• Player IDs must never authorize receipts, balances, payouts, or dashboard access.
• Private receipts are protected by unguessable receipt secrets.
• Public slip rows expose only public player IDs, never private account IDs.
• Order creation is rate-limited by client IP and configured trusted proxy header.
• Admin payout routes require admin basic auth and CSRF protection.
• Startup rejects missing required configuration values loaded through the environment.

• partner house edge inflates player ticket price and derives partner balance
• partner payout address is required and must match the configured Bitcoin network
• embed order creation works without a Hookedin session
• public player IDs and private account IDs are stored for partner reporting while public slip rows omit the private account ID
• multiple partner sites feed one continuous round ticket sequence
• partner win record creation is idempotent after settlement
• scanner payment recording and slip recalculation are idempotent
• admin payout generation excludes uncredited late payments
• published utility source files match the scripts in utilities/bin
• testing wallet receive indexes are reserved safely under concurrent CLI use