@render-foundation/utils 0.0.253 → 0.0.254

package/lib/esm/src/client/pg/v2Client.js

@@ -33,114 +33,34 @@ BigInt.prototype.toJSON = function () {
 // confirmed_amount = EUR, despite the column name); 1 render credit = EUR 0.25, so credits = EUR x 4.
 // job.render_amt / user_grant_spend.render_spent_delta are credits x 1e8.
 export const EUR_TO_CREDITS = BigInt(4);
-// Grant accounting window: otoy_grant mirrors OTOY RFG issuances from this date. Consumption against the
-// window counts EVERY job the user ran in it — buy-and-burn jobs consumed OTOY credits exactly like
-// emissions-funded ones (counting only emissions-attributed spend over-issued ~2.58M credits, 2026-08-04).
-export const GRANT_WINDOW_START = '2025-05-01';
 export const CREDIT_DECIMALS = BigInt(100000000); // 1e8
-// A grant is consumable for this long after issuance; whatever is left after that EXPIRES (2026-08-05
-// model change). A job can only draw grants issued within the lookback window before it ran.
-export const GRANT_LOOKBACK_DAYS = 60;
-export const GRANT_LOOKBACK_MS = GRANT_LOOKBACK_DAYS * 24 * 3600 * 1000;
-export const foldGrantWindow = (events, opts = {}) => {
-    const lookback = opts.lookbackMs ?? GRANT_LOOKBACK_MS;
-    const now = opts.now ?? Date.now();
-    const sorted = [...events].sort((a, b) => a.t - b.t || (a.amt > b.amt ? -1 : 1)); // credits first on ties
-    const buckets = [];
-    const jobs = [];
-    const remaining = (b) => b.amount - b.reversed - b.drawnEmissions - b.drawnMisrouted;
-    let beyond = BigInt(0);
-    for (const e of sorted) {
-        if (e.src === 'grant') {
-            if (e.amt > BigInt(0)) {
-                buckets.push({
-                    grantId: e.grantId,
-                    t: e.t,
-                    amount: e.amt,
-                    reversed: BigInt(0),
-                    drawnEmissions: BigInt(0),
-                    drawnMisrouted: BigInt(0),
-                    expired: BigInt(0),
-                    left: BigInt(0),
-                });
-            }
-            else {
-                let claw = -e.amt; // clawback hits remaining capacity oldest-first; excess is dropped
-                for (const b of buckets) {
-                    if (claw <= BigInt(0))
-                        break;
-                    const take = remaining(b) < claw ? remaining(b) : claw;
-                    if (take > BigInt(0)) {
-                        b.reversed += take;
-                        claw -= take;
-                    }
-                }
-            }
-        }
-        else {
-            let need = -e.amt;
-            const total = need;
-            let emissionsLeft = e.emissions ?? need; // no split provided -> count it all as emissions
-            let jobEm = BigInt(0);
-            let jobMis = BigInt(0);
-            for (const b of buckets) {
-                if (need <= BigInt(0))
-                    break;
-                if (b.t + lookback < e.t)
-                    continue; // grant expired before this job ran
-                const take = remaining(b) < need ? remaining(b) : need;
-                if (take <= BigInt(0))
-                    continue;
-                const em = emissionsLeft < take ? emissionsLeft : take;
-                b.drawnEmissions += em;
-                b.drawnMisrouted += take - em;
-                jobEm += em;
-                jobMis += take - em;
-                emissionsLeft -= em;
-                need -= take;
-            }
-            beyond += need;
-            jobs.push({
-                id: e.id,
-                t: e.t,
-                need: total,
-                drawnEmissions: jobEm,
-                drawnMisrouted: jobMis,
-                beyond: need,
-            });
-        }
-    }
-    let avail = BigInt(0);
-    let expired = BigInt(0);
-    let usedEmissions = BigInt(0);
-    let usedMisrouted = BigInt(0);
+/**
+ * Pure core of the grant allotment: fold a user's OTOY grants against what's already been spent.
+ *
+ * consumed = attributedSpend (spend already stamped with an otoy_grant_id)
+ *          + correctionSettled (jobs whose grant is already being settled by a burn_correction)
+ *
+ * The correctionSettled term is the DOUBLE-SPEND GUARD: an escrow_credit correction means we're
+ * recovering that job's dollars from escrow, so its grant is already committed. Counting it here stops
+ * the same grant from also funding a future emissions burn.
+ *
+ * fifoGrantId = the oldest grant still holding room, i.e. the one the next spend draws from.
+ */
+export const foldGrantAllotment = (grants, attributedSpend, correctionSettled) => {
+    const granted = grants.reduce((s, g) => s + g.amountCredits, BigInt(0));
+    const consumed = (attributedSpend > BigInt(0) ? attributedSpend : BigInt(0)) +
+        (correctionSettled > BigInt(0) ? correctionSettled : BigInt(0));
+    const avail = granted > consumed ? granted - consumed : BigInt(0);
+    let drawn = consumed;
     let fifoGrantId;
-    for (const b of buckets) {
-        usedEmissions += b.drawnEmissions;
-        usedMisrouted += b.drawnMisrouted;
-        const rem = remaining(b);
-        if (b.t + lookback < now) {
-            b.expired = rem;
-        }
-        else {
-            b.left = rem;
-            avail += rem;
-            if (fifoGrantId === undefined && rem > BigInt(0) && b.grantId !== undefined)
-                fifoGrantId = b.grantId;
+    for (const g of grants) {
+        if (drawn < g.amountCredits) {
+            fifoGrantId = g.id;
+            break;
         }
-        expired += b.expired;
+        drawn -= g.amountCredits;
     }
-    return {
-        avail,
-        beyondGrants: beyond,
-        jobCharged: usedEmissions + usedMisrouted,
-        usedEmissions,
-        usedMisrouted,
-        expired,
-        buckets,
-        jobs,
-        fifoGrantId,
-    };
+    return { granted, consumed, avail, fifoGrantId };
 };
 import { begin } from './base';
 import moment from 'moment';
@@ -270,50 +190,63 @@ export const pgClient = (config) => {
         const out = {};
         if (!p.userIds.length)
             return out;
-        // Raw event stream, folded in code (foldGrantWindow — per-grant buckets, 60-day consumable window,
-        // reversals clamp capacity, only jobs create beyond-grants). SQL can't express the bucketed clamp.
-        const evRes = await sql `
-      select user_id::text as u, coalesce(otoy_created_at, ${GRANT_WINDOW_START}::timestamp) as t,
-             (amount_credits * 4 * 1e8)::numeric::text as amt, 'grant' as src, id as gid
-        from otoy_grant where user_id = any(${p.userIds}::uuid[])
-      union all
-      select user_id::text, ${GRANT_WINDOW_START}::timestamp, sum(render_spent_delta)::text, 'grant', null
-        from user_grant_spend
-       where user_id = any(${p.userIds}::uuid[]) and render_spent_delta > 0 and otoy_grant_id is null
-       group by user_id
-      union all
-      select user_id::text, created_at, (-render_spent_delta)::text, 'grant', null
-        from user_grant_spend
-       where user_id = any(${p.userIds}::uuid[]) and render_spent_delta > 0 and otoy_grant_id is not null
-      union all
-      select user_id, completed_at, (-render_amt)::text, 'job', null
-        from job
-       where user_id = any(${p.userIds}::text[]) and completed_at >= ${GRANT_WINDOW_START}::timestamp
-    `.execute(db); // db is always a Kysely trx at runtime
-        const byUser = new Map();
-        for (const r of evRes.rows) {
-            const arr = byUser.get(r.u) ?? [];
-            arr.push({
-                t: new Date(r.t).getTime(),
-                amt: BigInt(Math.round(Number(r.amt))),
-                src: r.src,
-                grantId: r.gid ?? undefined,
+        const grants = await db
+            .selectFrom(OTOY_GRANT_TABLE)
+            .select(['id', 'user_id', 'amount_credits', 'otoy_created_at'])
+            .where('user_id', 'in', p.userIds)
+            .orderBy('otoy_created_at', 'asc')
+            .orderBy('id', 'asc')
+            .execute();
+        if (!grants.length)
+            return out;
+        // Anything already booked against a pool grant, in EITHER direction:
+        //  - negative delta = spend drawn from the grant (this mechanism)
+        //  - positive delta = the grant was CREDITED into current_user_grant_spend (the one-off canary
+        //    route). That balance is already handed to the caller separately, so leaving it in the pool too
+        //    would hand out the same grant twice.
+        // Hence abs(): both directions retire pool capacity.
+        const spent = await db
+            .selectFrom(USER_GRANT_SPEND_TABLE)
+            .select((eb) => [
+            'user_id',
+            eb.fn.sum(sql `abs(render_spent_delta)`).as('net'),
+        ])
+            .where('user_id', 'in', p.userIds)
+            .where('otoy_grant_id', 'is not', null)
+            .groupBy('user_id')
+            .execute();
+        // jobs already settled by a burn correction — their grant is spoken for (double-spend guard)
+        const corrected = await db
+            .selectFrom(`${JOB_TABLE} as j`)
+            .innerJoin(`${BURN_CORRECTION_TABLE} as bc`, 'bc.job_id', 'j.id')
+            .select((eb) => ['j.user_id as user_id', eb.fn.sum('j.render_amt').as('amt')])
+            .where('j.user_id', 'in', p.userIds)
+            .groupBy('j.user_id')
+            .execute();
+        const spentBy = new Map(spent.map((r) => [r.user_id, BigInt(r.net ?? 0)]));
+        const corrBy = new Map(corrected.map((r) => [r.user_id, BigInt(r.amt ?? 0)]));
+        for (const g of grants) {
+            const u = g.user_id;
+            const cur = out[u] ??
+                (out[u] = { userId: u, granted: BigInt(0), consumed: BigInt(0), avail: BigInt(0), grants: [] });
+            // amount_credits is numeric EUR — truncate to whole base units after the x4 conversion
+            const credits = (BigInt(Math.round(Number(g.amount_credits) * 1e8)) * EUR_TO_CREDITS);
+            cur.granted += credits;
+            cur.grants.push({
+                id: Number(g.id),
+                amountCredits: credits,
+                createdAt: g.otoy_created_at ? new Date(g.otoy_created_at) : null,
             });
-            byUser.set(r.u, arr);
         }
-        for (const [u, events] of byUser) {
-            const f = foldGrantWindow(events);
-            out[u] = {
-                userId: u,
-                granted: events.reduce((a, e) => (e.src === 'grant' && e.amt > BigInt(0) ? a + e.amt : a), BigInt(0)),
-                consumed: f.jobCharged,
-                avail: f.avail,
-                expired: f.expired,
-                fifoGrantId: f.fifoGrantId,
-            };
-            if (f.beyondGrants > BigInt(0)) {
-                log.info(`grant allotment ${u}: ${f.beyondGrants} beyond grants (purchase-paid at the time), ` +
-                    `${f.expired} expired past the ${GRANT_LOOKBACK_DAYS}d window — avail ${f.avail}`);
+        for (const u of Object.keys(out)) {
+            const attributed = spentBy.get(u) ?? BigInt(0); // abs() — spend drawn or grant already credited
+            const viaCorrection = corrBy.get(u) ?? BigInt(0);
+            const f = foldGrantAllotment(out[u].grants, attributed, viaCorrection);
+            out[u].granted = f.granted;
+            out[u].consumed = f.consumed;
+            out[u].avail = f.avail;
+            if (viaCorrection > BigInt(0)) {
+                log.info(`grant allotment ${u}: granted ${f.granted} - attributed ${attributed} - correction-settled ${viaCorrection} = ${f.avail}`);
             }
         }
         return out;
@@ -395,7 +328,7 @@ export const pgClient = (config) => {
         const sequenceNumbers = [];
         const dbEpochIds = [];
         for (const bt of bts) {
-            let { solKey: toSolKey, seq, createdAt, amount, upgradeBracket, priorSupply, points, epochId, sender, } = bt;
+            let { solKey: toSolKey, seq, createdAt, amount, upgradeBracket, priorSupply, points, epochId, } = bt;
             let entityId;
             if (toSolKey && toSolKey != '') {
                 entityId = await getOrInsertEntity(db, { solKey: toSolKey });
@@ -416,7 +349,6 @@ export const pgClient = (config) => {
                 prior_supply: priorSupply,
                 points: points,
                 epoch_id: dbEpochId,
-                sender: sender,
             })
                 .onConflict((oc) => oc.column('sequence').doUpdateSet({
                 created_at: createdAt,
@@ -426,7 +358,6 @@ export const pgClient = (config) => {
                 points: points,
                 epoch_id: dbEpochId,
                 entity_id: entityId,
-                sender: sender,
             }))
                 .returning('sequence');
             const c = q.compile();
@@ -1169,13 +1100,16 @@ export const pgClient = (config) => {
                         return;
                     }
                 }
-                // FIFO-attribute this spend to the user's oldest LIVE OTOY grant that still has room (the fold
-                // already applies the lookback window). Stamping otoy_grant_id is what shows the draw in the
-                // admin drill-down — an unattributed row would leave the grant looking unspent there.
+                // FIFO-attribute this spend to the user's oldest OTOY grant that still has room. Stamping
+                // otoy_grant_id is what makes getGrantAllotments count it as consumed — an unattributed row
+                // would leave the grant looking unspent and let it fund a second burn.
                 let otoyGrantId = p.otoyGrantId;
                 if (otoyGrantId === undefined && p.renderSpentDelta < BigInt(0)) {
                     const allots = await getGrantAllotments(db.trx, { userIds: [p.userId] }, log);
-                    otoyGrantId = allots[p.userId]?.fifoGrantId;
+                    const a = allots[p.userId];
+                    if (a) {
+                        otoyGrantId = foldGrantAllotment(a.grants, a.consumed, BigInt(0)).fifoGrantId;
+                    }
                 }
                 const v = {
                     user_id: p.userId,
@@ -1528,70 +1462,133 @@ export const pgClient = (config) => {
             return burns;
         },
         async fetchBurnsPage(db, f, log = consoleLogger) {
-            const lastId = f.cursor ? atob(f.cursor) : undefined;
-            let q = db.trx
-                .selectFrom('burn')
-                .selectAll('burn')
-                .innerJoin('sol_tx', 'sol_tx.id', 'burn.sol_tx_id')
-                .select(['sol_tx.executed_at', 'sol_tx.sig']);
-            if (!f.inclManual) {
-                q = q.where('burn.usdc_spent', '>', String(0));
-            }
-            if (f.executedAfter) {
-                q = q.where('sol_tx.executed_at', '>=', f.executedAfter);
-            }
-            if (f.executedBefore) {
-                q = q.where('sol_tx.executed_at', '<=', f.executedBefore);
-            }
-            if (f.sig) {
-                // Exact match, not a prefix: sol_tx.sig is unique, so this is an index hit returning at most one row.
-                q = q.where('sol_tx.sig', '=', f.sig);
+            const params = [];
+            const p = (v) => {
+                params.push(v);
+                return `$${params.length}`;
+            };
+            // Decode cursor — supports new {t,id,ea} format and legacy bare-id format.
+            let cursorEa;
+            let cursorType;
+            let cursorId;
+            if (f.cursor) {
+                const raw = atob(f.cursor);
+                try {
+                    const c = JSON.parse(raw);
+                    cursorEa = new Date(c.ea);
+                    cursorType = c.t;
+                    cursorId = c.id;
+                }
+                catch {
+                    // Legacy cursor: bare burn.id — treat as buy-burn cursor.
+                    cursorId = Number(raw);
+                    cursorType = 'buy';
+                }
             }
+            // Shared WHERE fragments pushed into each union leg for index use.
+            const dateFilters = [];
+            if (f.executedAfter)
+                dateFilters.push(`st.executed_at >= ${p(f.executedAfter)}`);
+            if (f.executedBefore)
+                dateFilters.push(`st.executed_at <= ${p(f.executedBefore)}`);
+            const sigFilter = f.sig ? `st.sig = ${p(f.sig)}` : '';
+            // Buy-burn leg
+            const buyWhere = [...dateFilters];
+            if (!f.inclManual)
+                buyWhere.push('b.usdc_spent > 0');
+            if (sigFilter)
+                buyWhere.push(sigFilter);
             if (f.jobId !== undefined) {
-                // "Which burn consumed this job?" — job.burn_id is the FK, so resolve it as a subquery rather than
-                // joining `job` into the page query, which would multiply rows by job count and break both the limit
-                // and the cursor.
-                q = q.where('burn.id', 'in', (eb) => eb
-                    .selectFrom('job')
-                    .select('job.burn_id')
-                    .where('job.id', '=', String(f.jobId)));
-            }
-            if (lastId) {
-                q = q.where('burn.id', '>', lastId);
+                buyWhere.push(`b.id IN (SELECT burn_id FROM job WHERE id = ${p(f.jobId)})`);
+            }
+            const buyWhereClause = buyWhere.length ? `WHERE ${buyWhere.join(' AND ')}` : '';
+            const buySql = `
+        SELECT 'buy'::text AS type, b.id::bigint AS sortid, b.id AS id,
+               st.executed_at, b.priced_at, b.burned::text AS burned,
+               b.usdc_spent::text AS usdc_spent, b.quote_amt::text AS quote_amt,
+               b.tags, st.sig, b.render_to_usdc, b.eur_to_usdc,
+               coalesce(b.from_escrow_usdc, 0)::text AS from_escrow_usdc,
+               b.down_correction_id, b.escrow_correction_id,
+               b.marked_burned_at
+          FROM burn b
+         INNER JOIN sol_tx st ON st.id = b.sol_tx_id
+         ${buyWhereClause}`;
+            // Grant-burn leg
+            const grantWhere = [...dateFilters];
+            if (sigFilter)
+                grantWhere.push(sigFilter);
+            if (f.jobId !== undefined) {
+                grantWhere.push(`gb.id IN (SELECT grant_burn_id FROM job WHERE id = ${p(f.jobId)})`);
+            }
+            const grantWhereClause = grantWhere.length ? `WHERE ${grantWhere.join(' AND ')}` : '';
+            const grantSql = `
+        SELECT 'grant'::text AS type, gb.id::bigint AS sortid, gb.id AS id,
+               st.executed_at, null::timestamp AS priced_at, gb.burned::text AS burned,
+               '0' AS usdc_spent, '0' AS quote_amt,
+               gb.tags, st.sig, null::float8 AS render_to_usdc, null::float8 AS eur_to_usdc,
+               '0' AS from_escrow_usdc,
+               null::bigint AS down_correction_id, null::bigint AS escrow_correction_id,
+               gb.marked_burned_at
+          FROM grant_burn gb
+         INNER JOIN sol_tx st ON st.id = gb.sol_tx_id
+         ${grantWhereClause}`;
+            // Cursor filter on the outer query — row comparison for deterministic paging.
+            let cursorFilter = '';
+            if (cursorEa && cursorType && cursorId !== undefined) {
+                cursorFilter = `WHERE (u.executed_at, u.type, u.sortid) > (${p(cursorEa)}, ${p(cursorType)}, ${p(cursorId)})`;
+            }
+            else if (cursorId !== undefined) {
+                // Legacy cursor fallback: only buy burns, ordered by id.
+                cursorFilter = `WHERE u.type = 'buy' AND u.sortid > ${p(cursorId)}`;
             }
             const limit = f.limit ?? 1000;
-            q = q.limit(limit).orderBy('burn.id');
-            const comp = q.compile();
-            const { rows } = await timedQuery(pgPool, comp.sql, comp.parameters, 'fetchBurnsPage', log);
+            const sql = `
+        SELECT u.* FROM (
+          ${buySql}
+          UNION ALL
+          ${grantSql}
+        ) u
+        ${cursorFilter}
+        ORDER BY u.executed_at ASC, u.type, u.sortid
+        LIMIT ${p(limit)}`;
+            const { rows } = await timedQuery(pgPool, sql, params, 'fetchBurnsPage', log);
             const burns = rows.map((r) => ({
                 jobs: [],
                 id: Number(r.id),
-                renderToUsdc: r.render_to_usdc,
+                type: r.type,
+                renderToUsdc: r.render_to_usdc ?? undefined,
                 solTx: r.sig,
                 executedAt: r.executed_at,
-                pricedAt: r.priced_at,
+                pricedAt: r.priced_at ?? undefined,
                 usdcSpent: BigInt(r.usdc_spent ?? 0),
                 quoteAmt: BigInt(r.quote_amt ?? 0),
                 burned: BigInt(r.burned),
-                eurToUsdc: r.eur_to_usdc,
+                eurToUsdc: r.eur_to_usdc ?? undefined,
                 markedBurnedAt: r.marked_burned_at,
                 tags: r.tags ? r.tags.split(',') : [],
+                fromEscrowUsdc: BigInt(r.from_escrow_usdc ?? 0),
+                downCorrectionId: r.down_correction_id ? Number(r.down_correction_id) : undefined,
+                escrowCorrectionId: r.escrow_correction_id ? Number(r.escrow_correction_id) : undefined,
             }));
             return {
                 burns,
-                // Only hand back a cursor on a full page; a short page means we're done.
                 cursor: burns.length === limit
-                    ? btoa(String(burns[burns.length - 1].id))
+                    ? btoa(JSON.stringify({
+                        ea: rows[burns.length - 1].executed_at,
+                        t: rows[burns.length - 1].type,
+                        id: rows[burns.length - 1].sortid,
+                    }))
                     : undefined,
             };
         },
-        async fetchBurnJobs(db, burnId, log = consoleLogger) {
+        async fetchBurnJobs(db, burnId, burnType = 'buy', log = consoleLogger) {
+            const fk = burnType === 'grant' ? 'grant_burn_id' : 'burn_id';
             const rows = await db.trx
                 .selectFrom('job')
                 .selectAll('job')
-                .where('burn_id', '=', String(burnId))
+                .where(fk, '=', String(burnId))
                 .execute();
-            log.debug(`fetchBurnJobs burn ${burnId} -> ${rows.length} jobs`);
+            log.debug(`fetchBurnJobs ${burnType} ${burnId} -> ${rows.length} jobs`);
             return rows.map((r) => ({
                 id: Number(r.id),
                 completedAt: r.completed_at,
@@ -1915,8 +1912,6 @@ export const pgClient = (config) => {
                     usdc_spent: p.usdcSpent ?? null,
                     correction_id: p.correctionId ?? null,
                     correction_render: p.correctionRender ?? null,
-                    usage_from: p.usageFrom ?? null,
-                    usage_to: p.usageTo ?? null,
                 })
                     .onConflict((oc) => oc.column('tx_signature').doNothing())
                     .executeTakeFirst();