Gaming

npm install --global @parix/cli@latest
parix --version

parix auth login
parix auth status
parix database list --json

export PARIX_DATABASE_ID="db_replace_with_uuid"

[
  { "id": "810000000000000001", "ledger": 8001, "code": 300, "flags": 8 },
  { "id": "810000000000000002", "ledger": 8001, "code": 200, "flags": 10 },
  { "id": "810000000000000003", "ledger": 8001, "code": 100, "flags": 10 },
  { "id": "810000000000000004", "ledger": 8001, "code": 100, "flags": 10 },
  { "id": "810000000000000005", "ledger": 8001, "code": 400, "flags": 8 }
]

parix tb create-accounts "$PARIX_DATABASE_ID" --file ./gaming-accounts.json --json

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 820000000000000001 \
  --from 810000000000000001 \
  --to 810000000000000002 \
  --amount 5000 \
  --ledger 8001 \
  --code 10 \
  --json

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 820000000000000002 \
  --from 810000000000000002 \
  --to 810000000000000003 \
  --amount 1500 \
  --ledger 8001 \
  --code 11 \
  --json

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 820000000000000003 \
  --from 810000000000000003 \
  --to 810000000000000001 \
  --amount 200 \
  --ledger 8001 \
  --code 20 \
  --json

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 820000000000000004 \
  --from 810000000000000003 \
  --to 810000000000000005 \
  --amount 50 \
  --ledger 8001 \
  --code 21 \
  --json

[
  {
    "id": "820000000000000005",
    "debit_account_id": "810000000000000003",
    "credit_account_id": "810000000000000004",
    "amount": "100",
    "ledger": 8001,
    "code": 30,
    "flags": 1
  },
  {
    "id": "820000000000000006",
    "debit_account_id": "810000000000000003",
    "credit_account_id": "810000000000000001",
    "amount": "5",
    "ledger": 8001,
    "code": 31,
    "flags": 0
  }
]

parix tb create-transfers "$PARIX_DATABASE_ID" --file ./gaming-trade.json --json
parix tb lookup-transfers "$PARIX_DATABASE_ID" --ids 820000000000000005,820000000000000006 --json
parix tb query-accounts "$PARIX_DATABASE_ID" --ledger 8001 --limit 20 --json

import type {
  Account,
  CreateAccountResult,
  CreateTransferResult,
  Transfer,
} from '@parix/tigerbeetle-node';
import { AccountFlags, CreateTransferError, TransferFlags, createClient } from '@parix/tigerbeetle-node';

const client = createClient({
  baseUrl: process.env.PARIX_BASE_URL ?? 'https://parix.io',
  apiKey: mustGetEnv('PARIX_API_KEY'),
  databaseId: mustGetEnv('PARIX_DATABASE_ID'),
});

const ledger = 8001;
const accountId = {
  treasury: 810000000000000001n,
  rewardPool: 810000000000000002n,
  alice: 810000000000000003n,
  bob: 810000000000000004n,
  sink: 810000000000000005n,
} as const;

// Persist these with their game events before submission. Never call an ID generator in retry code.
const transferId = {
  fundRewardPool: 820000000000000001n,
  grantAlice: 820000000000000002n,
  purchaseAlice: 820000000000000003n,
  burnAlice: 820000000000000004n,
  tradePrincipal: 820000000000000005n,
  tradeFee: 820000000000000006n,
  compensatePrincipal: 820000000000000007n,
  compensateFee: 820000000000000008n,
} as const;

function account(id: bigint, code: number, flags: number): Account {
  return {
    id,
    debits_pending: 0n,
    debits_posted: 0n,
    credits_pending: 0n,
    credits_posted: 0n,
    user_data_128: 0n,
    user_data_64: 0n,
    user_data_32: 0,
    reserved: 0,
    ledger,
    code,
    flags,
    timestamp: 0n,
  };
}

function transfer(input: {
  id: bigint;
  debitAccountId: bigint;
  creditAccountId: bigint;
  amount: bigint;
  code: number;
  flags?: number;
}): Transfer {
  return {
    id: input.id,
    debit_account_id: input.debitAccountId,
    credit_account_id: input.creditAccountId,
    amount: input.amount,
    pending_id: 0n,
    user_data_128: 0n,
    user_data_64: 0n,
    user_data_32: 0,
    timeout: 0,
    ledger,
    code: input.code,
    flags: input.flags ?? TransferFlags.none,
    timestamp: 0n,
  };
}

function assertEmptyResults(operation: string, results: CreateAccountResult[] | CreateTransferResult[]): void {
  if (results.length === 0) return;
  const capacityDecline = results.some((item) => item.result === CreateTransferError.exceeds_credits);
  throw new Error(
    `${operation} rejected${capacityDecline ? ' (capacity)' : ''}: ${JSON.stringify(results)}`,
  );
}

function getHttpStatus(cause: unknown): number | undefined {
  if (!cause || typeof cause !== 'object' || !('status' in cause)) return undefined;
  const status = (cause as { status?: unknown }).status;
  return typeof status === 'number' ? status : undefined;
}

function wasDefinitelyRejected(cause: unknown): boolean {
  const status = getHttpStatus(cause);
  return status !== undefined && [400, 401, 402, 403, 404, 409, 429].includes(status);
}

function hasSameImmutableAccountFields(actual: Account, intended: Account): boolean {
  return (
    actual.id === intended.id &&
    actual.user_data_128 === intended.user_data_128 &&
    actual.user_data_64 === intended.user_data_64 &&
    actual.user_data_32 === intended.user_data_32 &&
    actual.reserved === intended.reserved &&
    actual.ledger === intended.ledger &&
    actual.code === intended.code &&
    actual.flags === intended.flags
  );
}

function hasSameImmutableFields(actual: Transfer, intended: Transfer): boolean {
  return (
    actual.id === intended.id &&
    actual.debit_account_id === intended.debit_account_id &&
    actual.credit_account_id === intended.credit_account_id &&
    actual.amount === intended.amount &&
    actual.pending_id === intended.pending_id &&
    actual.user_data_128 === intended.user_data_128 &&
    actual.user_data_64 === intended.user_data_64 &&
    actual.user_data_32 === intended.user_data_32 &&
    actual.timeout === intended.timeout &&
    actual.ledger === intended.ledger &&
    actual.code === intended.code &&
    actual.flags === intended.flags
  );
}

async function accountsExistExactly(batch: Account[]): Promise<boolean> {
  const found = await client.lookupAccounts(batch.map((item) => item.id));
  if (found.length === 0) return false;

  const intendedById = new Map(batch.map((item) => [item.id, item]));
  if (
    found.length !== batch.length ||
    !found.every((item) => {
      const intended = intendedById.get(item.id);
      return intended !== undefined && hasSameImmutableAccountFields(item, intended);
    })
  ) {
    throw new Error('Account IDs are only partially present or exist with different immutable fields');
  }

  return true;
}

async function transfersExistExactly(label: string, batch: Transfer[]): Promise<boolean> {
  const found = await client.lookupTransfers(batch.map((item) => item.id));
  if (found.length === 0) return false;

  const intendedById = new Map(batch.map((item) => [item.id, item]));
  if (
    found.length !== batch.length ||
    !found.every((item) => {
      const intended = intendedById.get(item.id);
      return intended !== undefined && hasSameImmutableFields(item, intended);
    })
  ) {
    throw new Error(`${label} IDs are only partially present or exist with different immutable fields`);
  }

  return true;
}

async function createAccountsOrResolveAmbiguity(batch: Account[]): Promise<void> {
  // This lookup makes a new process safe after an earlier process committed but
  // stopped before persisting the HTTP response.
  if (await accountsExistExactly(batch)) return;

  let results: CreateAccountResult[] | CreateTransferResult[];

  try {
    results = await client.createAccounts(batch);
  } catch (cause) {
    if (wasDefinitelyRejected(cause)) throw cause;

    if (await accountsExistExactly(batch)) return;
    throw new Error('Accounts were not found; retry only with the same IDs and payload', { cause });
  }

  if (await accountsExistExactly(batch)) return;
  if (results.length === 0) {
    throw new Error('Account write was not confirmed by lookup; do not advance or change the payload');
  }
  assertEmptyResults('createAccounts', results);
}

async function createTransfersOrResolveAmbiguity(label: string, batch: Transfer[]): Promise<void> {
  // Stable-ID lookup is also the first step after a worker or process restart.
  if (await transfersExistExactly(label, batch)) return;

  let results: CreateAccountResult[] | CreateTransferResult[];

  try {
    results = await client.createTransfers(batch);
  } catch (cause) {
    if (wasDefinitelyRejected(cause)) throw cause;

    if (await transfersExistExactly(label, batch)) return;
    throw new Error(`${label} was not found; retry only with the same IDs and payload`, { cause });
  }

  if (await transfersExistExactly(label, batch)) return;
  if (results.length === 0) {
    throw new Error(`${label} was not confirmed by lookup; do not advance or change the payload`);
  }
  assertEmptyResults(label, results);
}

async function settleTrade(commitInventory: () => Promise<'committed' | 'rejected' | 'unknown'>): Promise<void> {
  const trade = [
    transfer({
      id: transferId.tradePrincipal,
      debitAccountId: accountId.alice,
      creditAccountId: accountId.bob,
      amount: 100n,
      code: 30,
      flags: TransferFlags.linked,
    }),
    transfer({
      id: transferId.tradeFee,
      debitAccountId: accountId.alice,
      creditAccountId: accountId.treasury,
      amount: 5n,
      code: 31,
      flags: TransferFlags.none,
    }),
  ];

  await createTransfersOrResolveAmbiguity('trade', trade);

  const inventoryOutcome = await commitInventory();
  if (inventoryOutcome === 'committed') return;
  if (inventoryOutcome === 'unknown') {
    throw new Error('Inventory outcome is ambiguous; look up the stable trade ID before compensation');
  }

  // Compensation is another linked ledger event; it never erases the original trade.
  await createTransfersOrResolveAmbiguity('trade compensation', [
    transfer({
      id: transferId.compensatePrincipal,
      debitAccountId: accountId.bob,
      creditAccountId: accountId.alice,
      amount: 100n,
      code: 40,
      flags: TransferFlags.linked,
    }),
    transfer({
      id: transferId.compensateFee,
      debitAccountId: accountId.treasury,
      creditAccountId: accountId.alice,
      amount: 5n,
      code: 41,
      flags: TransferFlags.none,
    }),
  ]);
}

async function main(): Promise<void> {
  const constrainedHistory = AccountFlags.history | AccountFlags.debits_must_not_exceed_credits;
  await createAccountsOrResolveAmbiguity([
    account(accountId.treasury, 300, AccountFlags.history),
    account(accountId.rewardPool, 200, constrainedHistory),
    account(accountId.alice, 100, constrainedHistory),
    account(accountId.bob, 100, constrainedHistory),
    account(accountId.sink, 400, AccountFlags.history),
  ]);

  await createTransfersOrResolveAmbiguity('fund reward pool', [
    transfer({
      id: transferId.fundRewardPool,
      debitAccountId: accountId.treasury,
      creditAccountId: accountId.rewardPool,
      amount: 5000n,
      code: 10,
    }),
  ]);

  await createTransfersOrResolveAmbiguity('grant Alice', [
    transfer({
      id: transferId.grantAlice,
      debitAccountId: accountId.rewardPool,
      creditAccountId: accountId.alice,
      amount: 1500n,
      code: 11,
    }),
  ]);

  await createTransfersOrResolveAmbiguity('purchase', [
    transfer({
      id: transferId.purchaseAlice,
      debitAccountId: accountId.alice,
      creditAccountId: accountId.treasury,
      amount: 200n,
      code: 20,
    }),
  ]);

  await createTransfersOrResolveAmbiguity('burn', [
    transfer({
      id: transferId.burnAlice,
      debitAccountId: accountId.alice,
      creditAccountId: accountId.sink,
      amount: 50n,
      code: 21,
    }),
  ]);

  // The real callback must be an idempotent application-DB transaction keyed by the trade ID.
  await settleTrade(async () => 'committed');
}

function mustGetEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

try {
  await main();
} finally {
  client.destroy();
}