Design spec: settlement-backend interface (gittensor-owned or self-built, pluggable either way)

[JSONbored]

Problem

We don't yet know whether the actual settlement/pooling layer for subnet-funded rewards ends up owned by gittensor (extending their existing registration/reward infrastructure) or needs to be self-built. Rather than block on that decision, the interface boundary between "AMS/ORB's work" and "money moves" can be designed now so either backend plugs in without a rewrite later.

Area

Product spec / architecture. Directly relevant to #4792 (rental ledger integration) — that issue's ledger/metering work should be built against this interface once it exists, not duplicated here.

Proposal

Define a settlement-backend interface, not an implementation: the contract a "pool funded, work discovered, work delivered, payout owed" flow needs, expressed so that (a) a future gittensor-owned settlement service, or (b) a self-built one, can sit behind it interchangeably. Cover, at interface level:

• What triggers a payout-eligible event (a merged PR against a subnet-funded repo) and what data that event needs to carry.
• How a pool's remaining balance/allocation is queried and decremented — read/write contract, not a specific ledger schema.
• Refund/dispute/partial-completion semantics at the interface level (the actual policy is Settlement & refund handling #4791's job once the model is chosen; this issue only defines where that policy plugs in).
• What "gittensor is structurally in the settlement path" requires at the interface level, if we build our own backend — i.e., the self-built version can't quietly disintermediate gittensor even as a fallback; the interface itself should make that structurally true, not just a business promise.

Deliverables

• A written interface spec (request/response shapes, event contract, not a chosen backend) that Rental ledger integration #4792's ledger work and Settlement & refund handling #4791's settlement-scenario work can both build against regardless of which backend ends up live.

Resources

• Rental ledger integration #4792 (rental ledger integration — the consumer of this interface)
• Settlement & refund handling #4791 (settlement scenarios — the policy that plugs into this interface's dispute/refund hooks)
• gittensor rental economics spec #4781 (the parent economics decision this interface needs to stay agnostic to)

Boundaries

Spec only — this issue does not decide whether we actually build our own settlement backend, it just makes that decision reversible/cheap later by not coupling the ledger work to one specific backend now. No real payment rails, wallet/hotkey material, or reward figures.

maintainer-only — planning/decision issue, not itself a build task.

[linear-code]

JSO-4200

[JSONbored]

Interface spec (resolved 2026-07-15)

Grounded in what already ships: #4792's LoopConsumptionEntry/buildLoopConsumptionEntry (packages/loopover-engine/src/loop-consumption.ts) is the settlement-model-agnostic metering core this interface wraps. This defines the contract a backend implements — no backend is chosen, no code beyond the interface types below.

1. The payout-eligible event

A payout-eligible event fires when a merged PR against a subnet-funded repo produces a completed (or killed, per #4792's "killed still bills" rule) LoopConsumptionEntry. The event carries:

type PayoutEligibleEvent = {
  poolId: string;              // the funded pool this consumption draws against (NOT tenantId --
                                // a subnet-funded pool is a different entity shape than an individual
                                // customer's tenant, per #6097's core-mechanism spec)
  entry: LoopConsumptionEntry; // #4792's existing shape, unmodified -- reused, not re-derived
  prNumber: number;
  repoFullName: string;
  mergedAtMs: number;
};

No new metering shape — this wraps LoopConsumptionEntry as-is. A settlement backend receives this event; it does not compute consumption itself.

2. Pool balance query/decrement contract

interface SettlementBackend {
  /** Read-only balance/allocation check -- called BEFORE work is claimed, so a pool that's already
   *  exhausted never gets more work queued against it. */
  getPoolBalance(poolId: string): Promise<{ remaining: number; exhausted: boolean }>;

  /** Called on a payout-eligible event. Decrements the pool and records the payout -- the ONE
   *  state-changing call in this interface. Idempotent per (poolId, entry.loopId): a retried delivery
   *  of the same event must never double-decrement. */
  recordPayout(event: PayoutEligibleEvent): Promise<{ payoutId: string; newBalance: number }>;

  /** #4791's settlement-scenario policy plugs in HERE, not into this interface's own logic -- this
   *  method only reports whether a payout was reversible at all (refund/dispute POLICY is #4791's job). */
  reversePayout(payoutId: string, reason: "refund" | "dispute" | "partial_completion"): Promise<{ ok: boolean }>;
}

getPoolBalance/recordPayout are read/write contract only — no specific ledger schema implied. A gittensor-owned backend and a self-built one both implement this same interface; #4792's future persistence work (blocked on #4940's storage abstraction, per its own resolved cross-reference) calls recordPayout and nothing else.

3. Structural gittensor-in-path requirement

If the self-built backend variant is ever live, SettlementBackend's recordPayout MUST require a subnetAttestation field (a reference to the subnet-side registration this pool traces back to) as a non-optional parameter — not a business-process promise, but a type-level requirement that makes "gittensor structurally in the settlement path" true even for the self-built fallback. A SettlementBackend implementation that cannot supply a real attestation cannot compile against this interface.

Non-goals

• No backend implementation, no chosen datastore, no ledger schema.
• No refund/dispute policy (Settlement & refund handling #4791's job — this interface only defines where that policy calls in).
• No pricing/reward-formula numbers (per gittensor rental economics spec #4781's own boundary, inherited here).

Consumers

#4792's future ledger-persistence work builds against recordPayout/getPoolBalance directly. #6097's core-mechanism spec references PayoutEligibleEvent's poolId field for its own subnet-registration shape.

[JSONbored]

Real follow-up filed (2026-07-15): #6314 is the concrete implementation issue that builds against this interface — properly milestoned, and natively linked as a sub-issue of #4792 (the pure decision core it persists) and blocked-by #4789/#4790 (per #4792's own original scope boundary). This spec doesn't just describe future work in prose; there's a real, navigable planning trail now.