- clis/lepton (@settlekit/lepton-cli): operator CLI (deploy/config/settlements/lineage/proof) on real domain logic - apps/agent-console: Next.js agentic-commerce surface, real domain logic (agent-services + citation-toll + attribution) - apps/stream-meter: Next.js live per-second streaming meter (RFB 4) on real @settlekit/streaming - packages/payouts-cpn (@settlekit/payouts-cpn): Circle CPN fiat off-ramp, credential-gated + local provider + tests - common: make ids.ts isomorphic (Web Crypto) so domain packages bundle into client components - wire clis/lepton into pnpm-workspace + vitest; 1031 tests, typecheck, all next builds green
310 lines
11 KiB
TypeScript
310 lines
11 KiB
TypeScript
/**
|
|
* The stream meter's data layer.
|
|
*
|
|
* This is NOT mocked JSON — it drives the real streaming-payment domain logic
|
|
* (@settlekit/streaming) so the UI shows exactly what the spine produces:
|
|
*
|
|
* - every stream is opened with `openStream({ ... })`, the real rate/accrual
|
|
* entry point. Accrual is never recomputed by hand here;
|
|
* - each stream is advanced over a FIXED millisecond clock (a mutable cursor),
|
|
* `reportFlow(false/true)` is called at the proof-of-flow drop windows so a
|
|
* delivery gap is genuinely not billed, and `settle(sink)` is awaited at
|
|
* checkpoint intervals to capture the real `StreamSettlement` batches;
|
|
* - the per-stream meter values come straight from `stream.snapshot()`, and the
|
|
* serializable projection comes from `recordFromStream()` — the same
|
|
* doc-projection the persistence layer uses.
|
|
*
|
|
* A fixed clock makes the dataset fully deterministic across renders and across
|
|
* `next build` prerenders (no `Date.now()`/`new Date()` on the server path).
|
|
* The browser meter (components/LiveMeter.tsx) constructs the SAME real
|
|
* `PaymentStream` via `buildLiveStream(() => Date.now())`, so the on-screen
|
|
* ticker is the genuine accrual function with a wall clock.
|
|
*
|
|
* Swap this module for a `StreamStore`-backed loader to go live.
|
|
*/
|
|
|
|
import { type Money, type PaymentNetwork, addMoney, money } from "@settlekit/common";
|
|
import {
|
|
type OpenStreamInput,
|
|
type StreamRecord,
|
|
type StreamSettlement,
|
|
type StreamSnapshot,
|
|
PaymentStream,
|
|
openStream,
|
|
recordFromStream,
|
|
} from "@settlekit/streaming";
|
|
|
|
/* -------------------------------------------------------------------------- */
|
|
/* Fixed clock */
|
|
/* -------------------------------------------------------------------------- */
|
|
|
|
/** Epoch ms of the deterministic build/SSR clock origin. */
|
|
export const FIXED_CLOCK_MS = Date.parse("2026-06-18T09:00:00.000Z");
|
|
|
|
/** Network used by the Lepton nanopayment lane. */
|
|
const NETWORK: PaymentNetwork = "arc";
|
|
|
|
/* -------------------------------------------------------------------------- */
|
|
/* Seeds: Owncast broadcasts + Navidrome listens */
|
|
/* -------------------------------------------------------------------------- */
|
|
|
|
export type StreamKind = "owncast" | "navidrome";
|
|
|
|
/** A flow drop: delivery pauses at `atSecond` for `forSeconds` (not billed). */
|
|
export interface FlowDrop {
|
|
atSecond: number;
|
|
forSeconds: number;
|
|
}
|
|
|
|
export interface StreamSeed {
|
|
id: string;
|
|
kind: StreamKind;
|
|
/** Payer (viewer/listener) address. */
|
|
payer: string;
|
|
/** Payee (streamer/artist) address. */
|
|
payee: string;
|
|
/** Authorized rate, decimal USDC per second (<= 6 dp). */
|
|
ratePerSecondUsdc: string;
|
|
/** Maximum total committed up front, decimal USDC (<= 6 dp). */
|
|
reserveUsdc: string;
|
|
/** How many seconds of the stream were consumed. */
|
|
watchedSeconds: number;
|
|
/** Delivery drops within the watched window (proof-of-flow pauses). */
|
|
flowDrops?: FlowDrop[];
|
|
/** Number of equal settlement checkpoints to capture across the window. */
|
|
checkpoints: number;
|
|
}
|
|
|
|
/** All seeded streams. */
|
|
export const SEEDS: readonly StreamSeed[] = [
|
|
{
|
|
id: "pst_owncast_keynote",
|
|
kind: "owncast",
|
|
payer: "0xv1ewer00000000000000000000000000000000a1",
|
|
payee: "0x57reamer000000000000000000000000000000b2",
|
|
ratePerSecondUsdc: "0.0002",
|
|
reserveUsdc: "0.5",
|
|
watchedSeconds: 900,
|
|
flowDrops: [{ atSecond: 300, forSeconds: 45 }],
|
|
checkpoints: 3,
|
|
},
|
|
{
|
|
id: "pst_navidrome_album",
|
|
kind: "navidrome",
|
|
payer: "0xl15tener0000000000000000000000000000a3c",
|
|
payee: "0xart15t00000000000000000000000000000000d4",
|
|
ratePerSecondUsdc: "0.0001",
|
|
reserveUsdc: "0.1",
|
|
watchedSeconds: 480,
|
|
flowDrops: [{ atSecond: 120, forSeconds: 20 }],
|
|
checkpoints: 2,
|
|
},
|
|
{
|
|
id: "pst_owncast_workshop",
|
|
kind: "owncast",
|
|
payer: "0xv1ewer00000000000000000000000000000000e5",
|
|
payee: "0x57reamer000000000000000000000000000000f6",
|
|
ratePerSecondUsdc: "0.00015",
|
|
reserveUsdc: "0.3",
|
|
watchedSeconds: 600,
|
|
checkpoints: 2,
|
|
},
|
|
];
|
|
|
|
/** The single stream the client meter animates live. */
|
|
export const LIVE_SEED: StreamSeed = SEEDS[0];
|
|
|
|
/* -------------------------------------------------------------------------- */
|
|
/* Building a real PaymentStream */
|
|
/* -------------------------------------------------------------------------- */
|
|
|
|
/**
|
|
* Build a real `PaymentStream` for a seed with a caller-supplied clock.
|
|
*
|
|
* Used by the client `LiveMeter` with `() => Date.now()` so the live ticker is
|
|
* the genuine accrual function rather than a re-implemented formula. Note this
|
|
* builds a *freshly opened* stream — it does not replay the historical flow
|
|
* drops/settlements (those belong to the deterministic server projection).
|
|
*/
|
|
export function buildLiveStream(seed: StreamSeed, now: () => number): PaymentStream {
|
|
const input: OpenStreamInput = {
|
|
id: seed.id,
|
|
payer: seed.payer,
|
|
payee: seed.payee,
|
|
network: NETWORK,
|
|
ratePerSecondUsdc: seed.ratePerSecondUsdc,
|
|
reserveUsdc: seed.reserveUsdc,
|
|
now,
|
|
};
|
|
return openStream(input);
|
|
}
|
|
|
|
/**
|
|
* Drive a seed deterministically over the fixed clock: advance a cursor in
|
|
* one-second steps, apply proof-of-flow drops as `reportFlow` pauses, and
|
|
* `settle()` at evenly spaced checkpoints. Returns the live stream plus the
|
|
* captured settlement batches.
|
|
*/
|
|
async function driveSeed(
|
|
seed: StreamSeed,
|
|
): Promise<{ stream: PaymentStream; settlements: StreamSettlement[] }> {
|
|
validateSeed(seed);
|
|
|
|
// Mutable cursor over the fixed clock. The stream reads `now()` lazily on
|
|
// every metered call, so advancing the cursor *is* the passage of time.
|
|
let cursorMs = FIXED_CLOCK_MS;
|
|
const now = (): number => cursorMs;
|
|
const stream = buildLiveStream(seed, now);
|
|
|
|
// Pre-compute the absolute seconds at which delivery drops begin/end.
|
|
const dropStart = new Map<number, number>(); // second -> forSeconds
|
|
const dropEnd = new Set<number>();
|
|
for (const drop of seed.flowDrops ?? []) {
|
|
dropStart.set(drop.atSecond, drop.forSeconds);
|
|
dropEnd.add(drop.atSecond + drop.forSeconds);
|
|
}
|
|
|
|
const settlements: StreamSettlement[] = [];
|
|
const sink = (s: StreamSettlement): void => {
|
|
settlements.push(s);
|
|
};
|
|
|
|
const interval =
|
|
seed.checkpoints > 0 ? Math.max(1, Math.floor(seed.watchedSeconds / seed.checkpoints)) : 0;
|
|
|
|
for (let second = 1; second <= seed.watchedSeconds; second++) {
|
|
cursorMs += 1000;
|
|
|
|
// Delivery drop begins: pause the meter via proof-of-flow.
|
|
if (dropStart.has(second)) {
|
|
stream.reportFlow(false);
|
|
}
|
|
// Delivery resumes: resume the flow-paused meter.
|
|
if (dropEnd.has(second)) {
|
|
stream.reportFlow(true);
|
|
}
|
|
|
|
// Capture a settlement checkpoint at evenly spaced intervals.
|
|
if (interval > 0 && second % interval === 0) {
|
|
await stream.settle(sink);
|
|
}
|
|
}
|
|
|
|
return { stream, settlements };
|
|
}
|
|
|
|
function validateSeed(seed: StreamSeed): void {
|
|
// money()/toBaseUnits throw RangeError on >6 dp or malformed strings; fail
|
|
// fast at the boundary with a clear message.
|
|
try {
|
|
money(seed.ratePerSecondUsdc);
|
|
money(seed.reserveUsdc);
|
|
} catch (error: unknown) {
|
|
const detail = error instanceof Error ? error.message : "invalid amount";
|
|
throw new Error(`Invalid seed ${seed.id}: ${detail}`);
|
|
}
|
|
if (!Number.isInteger(seed.watchedSeconds) || seed.watchedSeconds < 0) {
|
|
throw new Error(`Invalid seed ${seed.id}: watchedSeconds must be a non-negative integer`);
|
|
}
|
|
if (!Number.isInteger(seed.checkpoints) || seed.checkpoints < 0) {
|
|
throw new Error(`Invalid seed ${seed.id}: checkpoints must be a non-negative integer`);
|
|
}
|
|
}
|
|
|
|
/* -------------------------------------------------------------------------- */
|
|
/* Views + aggregation */
|
|
/* -------------------------------------------------------------------------- */
|
|
|
|
export interface StreamView {
|
|
id: string;
|
|
kind: StreamKind;
|
|
payer: string;
|
|
payee: string;
|
|
network: PaymentNetwork;
|
|
ratePerSecondUsdc: string;
|
|
snapshot: StreamSnapshot;
|
|
/** Serializable doc-projection (persistence/doc-projection pattern). */
|
|
record: StreamRecord;
|
|
}
|
|
|
|
export interface SettlementView {
|
|
streamId: string;
|
|
kind: StreamKind;
|
|
/** This batch's amount (decimal USDC string). */
|
|
amount: string;
|
|
/** Cumulative settled total after this batch (decimal USDC string). */
|
|
settledTotal: string;
|
|
at: string;
|
|
}
|
|
|
|
export interface MeterTotals {
|
|
activeStreams: number;
|
|
accrued: Money;
|
|
settled: Money;
|
|
due: Money;
|
|
refundable: Money;
|
|
}
|
|
|
|
export interface MeterContext {
|
|
streams: StreamView[];
|
|
settlements: SettlementView[];
|
|
totals: MeterTotals;
|
|
}
|
|
|
|
function sum(amounts: Money[]): Money {
|
|
return amounts.reduce<Money>((acc, m) => addMoney(acc, m), money("0"));
|
|
}
|
|
|
|
/**
|
|
* Build the full meter context from the real domain logic. Async because
|
|
* `settle()` is async. Deterministic: every clock read comes from the fixed
|
|
* cursor, so two calls produce identical results.
|
|
*/
|
|
export async function getMeterContext(): Promise<MeterContext> {
|
|
// Drive every seed (sequentially keeps the fixed-clock projection trivially
|
|
// deterministic and avoids any shared-cursor interleaving).
|
|
const driven: { seed: StreamSeed; stream: PaymentStream; settlements: StreamSettlement[] }[] = [];
|
|
for (const seed of SEEDS) {
|
|
const { stream, settlements } = await driveSeed(seed);
|
|
driven.push({ seed, stream, settlements });
|
|
}
|
|
|
|
const recordAt = new Date(FIXED_CLOCK_MS);
|
|
|
|
const streams: StreamView[] = driven.map(({ seed, stream }) => {
|
|
const snapshot = stream.snapshot();
|
|
return {
|
|
id: seed.id,
|
|
kind: seed.kind,
|
|
payer: seed.payer,
|
|
payee: seed.payee,
|
|
network: NETWORK,
|
|
ratePerSecondUsdc: snapshot.ratePerSecondUsdc,
|
|
snapshot,
|
|
record: recordFromStream(stream, recordAt),
|
|
};
|
|
});
|
|
|
|
const kindById = new Map<string, StreamKind>(driven.map(({ seed }) => [seed.id, seed.kind]));
|
|
|
|
const settlements: SettlementView[] = driven
|
|
.flatMap(({ settlements: batches }) => batches)
|
|
.map((s) => ({
|
|
streamId: s.streamId,
|
|
kind: kindById.get(s.streamId) ?? "owncast",
|
|
amount: s.amount.amount,
|
|
settledTotal: s.settledTotal.amount,
|
|
at: s.at,
|
|
}));
|
|
|
|
const totals: MeterTotals = {
|
|
activeStreams: streams.length,
|
|
accrued: sum(streams.map((s) => money(s.snapshot.accruedUsdc))),
|
|
settled: sum(streams.map((s) => money(s.snapshot.settledUsdc))),
|
|
due: sum(streams.map((s) => money(s.snapshot.dueUsdc))),
|
|
refundable: sum(streams.map((s) => money(s.snapshot.refundableUsdc))),
|
|
};
|
|
|
|
return { streams, settlements, totals };
|
|
}
|