Ledger y splits

La cascada de fees

computeFees() (domain/fee-engine.ts) es el único lugar donde se dividen los montos. Trabaja en las unidades base enteras del token (bigint), nunca con floats, y POST /api/v1/crypto/quote devuelve exactamente lo que calcula. Cada componente es un porcentaje del monto base (el precio en USD de la invoice), redondeado hacia abajo:

processing fee = base × 50 bps   (CRYPTO_PLATFORM_FEE_BPS, per-org override possible)
markup         = base × markup_percent        (the platform's own cut, 0–20 %)
partner_i      = base × splits[i].percent
fee_payer CUSTOMER: total = base + processing fee + markup;  seller net = base − Σ partners
fee_payer MERCHANT: total = base;                            seller net = base − fee − markup − Σ partners
invariant: seller net + Σ partners + markup + processing fee = total   (the seller absorbs rounding)

La invoice mínima es 1.00 USD; el USD equivale 1 : 1 a la stablecoin.

Ejemplo resuelto: 90 / 10 / 2 / 0.50

Una licencia de 100.00 USD vendida por Halden Type en la plataforma, con Kerning Weekly (un partner) llevándose el 10 %, un markup de plataforma del 2 % y el comprador pagando los fees:

{ "amount": "100.00", "fee_payer": "CUSTOMER", "markup_percent": 2,
  "merchant": "halden_type", "splits": [{ "account": "kerning_weekly", "percent": 10 }] }

Una vez confirmada la transferencia, una transacción de ledger balanceada (invoice:<id>:settlement) la registra:

El recibo del checkout dibuja el mismo corte como barra de split (seller · markup · fee; las partes de los partners no se le muestran al comprador), y la pestaña Ledger de la invoice en el dashboard muestra estas líneas con un check "Balanced". Con fee_payer: "MERCHANT" el comprador paga 100.00 y el fee y el markup salen de la parte de 90.00 del seller (87.50 neto).

Un sobrepago agrega un crédito a LIABILITY:REFUND_ESCROW:<invoice> por el excedente; ver Refunds.

Reglas del ledger

• Código de cuenta = TYPE:NAME[:holder]:NETWORK:CURRENCY. Cada red y cada token tienen sus propias cuentas, así que los saldos nunca mezclan cadenas ni monedas; el gas se registra en la moneda nativa (EXPENSE:ONCHAIN_GAS:…:POL).
• Los saldos cambian solo mediante postings armados por las factories de domain/ledger.ts (settlement, escrow, sweep, payout lock / complete / release, refund, fondeo del operador). Cada uno tiene una idempotency key determinística; volver a postearlo es un replay seguro.
• La base de datos hace cumplir los libros: los débitos igualan a los créditos por transacción, red y moneda (un trigger diferido que se chequea en el commit), las filas del journal son append-only y el saldo de una cuenta nunca puede quedar por debajo de cero (CHECK). Un sobregiro revierte todo el posting y aparece como 409 INSUFFICIENT_BALANCE.
• El ledger no tiene foreign keys a las organizations: los libros tienen que sobrevivir al borrado de un tenant. Las lecturas siempre se filtran por organization.

Dónde está el dinero on chain

La dirección de depósito recibe el pago. El job sweep del worker (cada 15 s) mueve los depósitos confirmados a la hot wallet (índice 0), recargando antes el depósito con gas nativo; el ledger mueve ONCHAIN_CUSTODY → HOT_WALLET y registra el gas. Los payouts y refunds se envían desde la hot wallet, nunca por encima de su saldo on-chain menos los envíos que todavía no se minaron.

Endpoints de lectura: GET /api/v1/crypto/balances?mode= (disponible y bloqueado por cuenta × red × token), GET /api/v1/crypto/ledger/transactions, GET /api/v1/crypto/ledger/accounts, GET /api/v1/crypto/overview.