Marketplaces

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": "710000000000000001", "ledger": 7001, "code": 100, "flags": 8 },
  { "id": "710000000000000002", "ledger": 7001, "code": 101, "flags": 10 },
  { "id": "710000000000000003", "ledger": 7001, "code": 201, "flags": 10 },
  { "id": "710000000000000004", "ledger": 7001, "code": 202, "flags": 10 },
  { "id": "710000000000000005", "ledger": 7001, "code": 301, "flags": 10 },
  { "id": "710000000000000006", "ledger": 7001, "code": 302, "flags": 10 },
  { "id": "710000000000000007", "ledger": 7001, "code": 401, "flags": 10 },
  { "id": "710000000000000008", "ledger": 7001, "code": 402, "flags": 10 }
]

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

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 720000000000000001 \
  --from 710000000000000001 \
  --to 710000000000000002 \
  --amount 10000 \
  --ledger 7001 \
  --code 100 \
  --json

[
  {
    "id": "720000000000000002",
    "debit_account_id": "710000000000000002",
    "credit_account_id": "710000000000000003",
    "amount": "8500",
    "ledger": 7001,
    "code": 110,
    "flags": 1
  },
  {
    "id": "720000000000000003",
    "debit_account_id": "710000000000000002",
    "credit_account_id": "710000000000000005",
    "amount": "1000",
    "ledger": 7001,
    "code": 111,
    "flags": 1
  },
  {
    "id": "720000000000000004",
    "debit_account_id": "710000000000000002",
    "credit_account_id": "710000000000000006",
    "amount": "500",
    "ledger": 7001,
    "code": 112,
    "flags": 0
  }
]

parix tb create-transfers "$PARIX_DATABASE_ID" --file ./marketplace-order-split.json --json
parix tb lookup-transfers "$PARIX_DATABASE_ID" --ids 720000000000000002,720000000000000003,720000000000000004 --json
parix tb query-accounts "$PARIX_DATABASE_ID" --ledger 7001 --limit 20 --json

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 720000000000000005 \
  --from 710000000000000003 \
  --to 710000000000000004 \
  --amount 8500 \
  --ledger 7001 \
  --code 120 \
  --json

[
  {
    "id": "720000000000000007",
    "debit_account_id": "710000000000000004",
    "credit_account_id": "710000000000000008",
    "amount": "1000",
    "ledger": 7001,
    "code": 140,
    "flags": 1
  },
  {
    "id": "720000000000000008",
    "debit_account_id": "710000000000000005",
    "credit_account_id": "710000000000000008",
    "amount": "200",
    "ledger": 7001,
    "code": 140,
    "flags": 1
  },
  {
    "id": "720000000000000009",
    "debit_account_id": "710000000000000006",
    "credit_account_id": "710000000000000008",
    "amount": "100",
    "ledger": 7001,
    "code": 140,
    "flags": 0
  }
]

parix tb create-transfers "$PARIX_DATABASE_ID" --file ./marketplace-partial-refund.json --json
parix tb lookup-transfers "$PARIX_DATABASE_ID" --ids 720000000000000007,720000000000000008,720000000000000009 --json

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 720000000000000006 \
  --from 710000000000000004 \
  --to 710000000000000007 \
  --amount 7500 \
  --ledger 7001 \
  --code 130 \
  --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 = 7001;
const accountId = {
  processorSettlement: 710000000000000001n,
  buyerClearing: 710000000000000002n,
  sellerPending: 710000000000000003n,
  sellerAvailable: 710000000000000004n,
  platformFee: 710000000000000005n,
  reserve: 710000000000000006n,
  payoutClearing: 710000000000000007n,
  refundClearing: 710000000000000008n,
} as const;

// Persist these IDs with the order before the first write. Never allocate IDs inside a retry loop.
const transferId = {
  capture: 720000000000000001n,
  sellerAllocation: 720000000000000002n,
  feeAllocation: 720000000000000003n,
  reserveAllocation: 720000000000000004n,
} 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;

    // A timeout, network failure, 500, or 503 can occur after commit. Lookup before retrying.
    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 main(): Promise<void> {
  const constrainedHistory = AccountFlags.history | AccountFlags.debits_must_not_exceed_credits;
  const accounts = [
    account(accountId.processorSettlement, 100, AccountFlags.history),
    account(accountId.buyerClearing, 101, constrainedHistory),
    account(accountId.sellerPending, 201, constrainedHistory),
    account(accountId.sellerAvailable, 202, constrainedHistory),
    account(accountId.platformFee, 301, constrainedHistory),
    account(accountId.reserve, 302, constrainedHistory),
    account(accountId.payoutClearing, 401, constrainedHistory),
    account(accountId.refundClearing, 402, constrainedHistory),
  ];

  await createAccountsOrResolveAmbiguity(accounts);

  await createTransfersOrResolveAmbiguity('capture', [
    transfer({
      id: transferId.capture,
      debitAccountId: accountId.processorSettlement,
      creditAccountId: accountId.buyerClearing,
      amount: 10000n,
      code: 100,
    }),
  ]);

  const allocation = [
    transfer({
      id: transferId.sellerAllocation,
      debitAccountId: accountId.buyerClearing,
      creditAccountId: accountId.sellerPending,
      amount: 8500n,
      code: 110,
      flags: TransferFlags.linked,
    }),
    transfer({
      id: transferId.feeAllocation,
      debitAccountId: accountId.buyerClearing,
      creditAccountId: accountId.platformFee,
      amount: 1000n,
      code: 111,
      flags: TransferFlags.linked,
    }),
    transfer({
      id: transferId.reserveAllocation,
      debitAccountId: accountId.buyerClearing,
      creditAccountId: accountId.reserve,
      amount: 500n,
      code: 112,
      flags: TransferFlags.none,
    }),
  ];

  await createTransfersOrResolveAmbiguity('order allocation', allocation);
}

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();
}