@ottochain/sdk 2.3.0 → 2.5.0

package/dist/types/apps/lending/credit-scoring.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Credit scoring via the identity + reputation app.
+ *
+ * A zk-loan's `creditScore` is NOT a self-asserted number — it is the borrower's on-chain identity
+ * REPUTATION, derived from their {@link Attestation} deltas (the identity app's reputation model:
+ * `baseReputation + Σ delta`, floored at `minReputation`). This module is the wire between the two
+ * apps: it computes the reputation-backed score, pins a lending rule that BINDS the score to a
+ * specific borrower identity (so a borrower cannot prove eligibility against someone else's
+ * reputation), and assembles the PRIVATE data context the borrower proves it over.
+ *
+ * Privacy boundary: the exact `creditScore` and `collateralValue` stay private (their keccak is the
+ * proof's `dataHash`); the `subject` (borrower identity) and the bounds are PUBLIC (pinned in the
+ * rule's `logicHash`). The zk proof attests "borrower X's reputation-backed score ≥ floor and
+ * collateral coverage ≥ ratio" without revealing the score or the holdings.
+ *
+ * Trust model: the proof binds the score to the borrower's identity, but the borrower supplies the
+ * score value. When reputation attestations are PUBLIC on-chain, a verifier can independently
+ * recompute the score and check the proof used it; when reputation is PRIVATE (off-chain / held
+ * credentials) the score is genuinely hidden. To make the score AUTHORITY-attested in zero knowledge
+ * (the strongest form), have the SP1 rule additionally `schnorr_verify` the reputation issuer's
+ * signature over `(subject, score)` — see {@link reputationAuthorityClause}.
+ */
+import { Attestation, ReputationConfig } from '../identity/index.js';
+import { type LendingRuleParams, type JsonLogicRule } from './eligibility.js';
+/** The reputation config fields credit scoring needs (a subset of the identity {@link ReputationConfig}). */
+export type CreditScoreConfig = Pick<ReputationConfig, 'baseReputation' | 'minReputation'>;
+/**
+ * Derive an agent's credit score from their identity reputation attestations:
+ * `baseReputation + Σ attestation.delta`, floored at `minReputation`. This IS the integration point —
+ * a zk-loan's creditScore is the borrower's identity reputation, not an independent number.
+ */
+export declare function reputationScore(attestations: ReadonlyArray<Pick<Attestation, 'delta'>>, config?: CreditScoreConfig): number;
+/** Params for a reputation-bound credit rule: the lending params plus the borrower identity it pins. */
+export interface ReputationCreditParams extends LendingRuleParams {
+    /** The borrower's identity (agent id / DID) the proven reputation score must belong to. */
+    borrowerId: string;
+}
+/** The PRIVATE data context a borrower proves a reputation-credit rule over (only `subject` is public). */
+export interface CreditDataContext {
+    /** PRIVATE — the borrower's collateral value. */
+    collateralValue: number;
+    /** PRIVATE — the borrower's reputation-derived credit score. */
+    creditScore: number;
+    /** PUBLIC — the borrower identity the score is bound to (pinned in the rule). */
+    subject: string;
+}
+/**
+ * The PUBLIC reputation-credit lending rule. Extends {@link lendingRule} (collateral coverage +
+ * optional credit-score floor) with a SUBJECT binding `subject === borrowerId`, so the proven score
+ * belongs to a specific identity — a borrower cannot prove eligibility against another agent's
+ * reputation. `borrowerId` and all bounds are literals, so pinning the rule pins them.
+ */
+export declare function reputationCreditRule(params: ReputationCreditParams): JsonLogicRule;
+/**
+ * Assemble the PRIVATE data context the borrower feeds to the zk-jlvm prover: the `creditScore` is
+ * their identity {@link reputationScore}, the `subject` is their identity. Only its keccak (`dataHash`)
+ * becomes public.
+ */
+export declare function buildCreditDataContext(args: {
+    borrowerId: string;
+    attestations: ReadonlyArray<Pick<Attestation, 'delta'>>;
+    collateralValue: number;
+    config?: CreditScoreConfig;
+}): CreditDataContext;
+/**
+ * OPTIONAL hardening — an authority-attested credit clause. ANDed into a rule, it makes the SP1 guest
+ * verify (in zero knowledge) the reputation issuer's Schnorr signature over the score, so the score is
+ * not merely borrower-supplied but ATTESTED.
+ *
+ * SECURITY: the authority's `authorityPubKey` MUST be a LITERAL pinned in the rule (it is part of the
+ * rule's keccak `logicHash`, so pinning it binds it) — NEVER read from the borrower's witness/private
+ * data, or the borrower could supply their own keypair and self-attest any score. Only the signature
+ * `repSig` and the signed `scoreCommit` ride on the (private) witness; the signature binds them to the
+ * pinned key. `scoreCommit` should commit the pinned `subject` + the proof's `dataHash` so a signature
+ * cannot be replayed for a different borrower/score.
+ *
+ * NOTE: producing a real signature + proof is required to exercise this end-to-end; the builder pins
+ * the structure so the on-chain rule and the prover agree. See the JLVM `schnorr_verify` opcode.
+ */
+export declare function reputationAuthorityClause(authorityPubKey: string): JsonLogicRule;

package/dist/types/apps/lending/eligibility.d.ts

@@ -0,0 +1,83 @@
+import type { Groth16WitnessMap, Groth16Bundle } from '../../zk/index.js';
+/** A JSON-Logic expression. */
+export type JsonLogicRule = Record<string, unknown>;
+/**
+ * Parameters for the standard collateral-coverage + credit-score lending rule.
+ *
+ * The literal bounds are baked INTO the rule expression, so they are part of its logicHash —
+ * pinning the rule pins the bounds. The numerator/denominator form expresses the LTV bound
+ * `collateralValue * 100 >= loanAmount * collateralRatioPct` without floating-point.
+ */
+export interface LendingRuleParams {
+    /** Required collateralization, as a percent of the loan (e.g. 150 = 150% over-collateralized). */
+    collateralRatioPct: number;
+    /** PUBLIC loan principal the rule is checked against. */
+    loanAmount: number;
+    /** Optional minimum credit score floor; omit to gate on collateral coverage only. */
+    minCreditScore?: number;
+}
+/**
+ * The PUBLIC lending rule, as a JSON-Logic predicate over the borrower's PRIVATE data context
+ * `{ collateralValue, creditScore }`. Evaluates to `true` iff the borrower is eligible:
+ *
+ *   collateralValue * 100 >= loanAmount * collateralRatioPct   (collateral coverage)
+ *   AND creditScore >= minCreditScore                          (if a floor is set)
+ *
+ * Only the predicate and its literal bounds are public; the data it is evaluated over
+ * (`collateralValue`, `creditScore`) is the prover's private witness — its keccak is the
+ * proof's `dataHash`, never revealed. This is the rule the zk-jlvm guest runs; its `exprHash`
+ * is pinned as the loan's `lendingRuleLogicHash`.
+ */
+export declare function lendingRule(params: LendingRuleParams): JsonLogicRule;
+/** The pinned public constants a zk-loan create-state carries so its origination guard is closed. */
+export interface PinnedLendingRule {
+    /** The PUBLIC rule expression (with literal bounds). */
+    rule: JsonLogicRule;
+    /** keccak256(canonicalize(rule)) — pinned as `lendingRuleLogicHash`; the proof's exprHash must equal it. */
+    logicHash: `0x${string}`;
+    /** keccak256(canonicalize(true)) — pinned as `keccakTrue`; a "rule == true" proof's outputHash. */
+    keccakTrue: `0x${string}`;
+    /** The SP1 program verifying key (bytes32, 0x-hex) for the eligibility circuit. */
+    vkey: `0x${string}`;
+}
+/**
+ * Pin a lending rule: produce the public rule plus the three constants the loan's origination
+ * guard binds against. `vkey` is the verifying key of the SP1 zk-jlvm program that runs the
+ * rule (supplied by the lender / deployment).
+ */
+export declare function pinLendingRule(params: LendingRuleParams, vkey: `0x${string}`): PinnedLendingRule;
+/** The pinned public references the origination guard reads off the loan state. */
+export interface OriginationGuardRefs {
+    /** State path to the pinned vkey (default `state.lendingRuleVKey`). */
+    vkeyVar?: string;
+    /** State path to the pinned logicHash (default `state.lendingRuleLogicHash`). */
+    logicHashVar?: string;
+    /** State path to the pinned keccakTrue (default `state.keccakTrue`). */
+    keccakTrueVar?: string;
+}
+/**
+ * Build the semi-private ORIGINATION guard expression.
+ *
+ * It verifies the SP1-Groth16 eligibility proof AND binds its committed public values to the
+ * pinned public rule. `publicValues = abi_encode(JlvmPublicValues{exprHash|dataHash|outputHash|ok})`
+ * is opaque to `groth16_verify`; the guard slices the `0x`-hex form with native JLVM `substr`
+ * (start, len) and re-`cat`s the `0x` prefix — there is no `jlvm_pv_decode` opcode. Clauses:
+ *
+ *   1. `groth16_verify(vkey, witness.publicValues, witness.proof)`  — the proof is valid
+ *   2. `exprHash   == logicHash`   (word 0, hex chars [2,66))         — it proved THE pinned rule
+ *   3. `outputHash == keccakTrue`  (word 2, hex chars [130,194))      — the rule evaluated to true
+ *   4. `ok == "01"`                (word 3 final pair, [256,258))      — the JLVM run did not error
+ *
+ * This is the closed boolean an asset `mintPolicy` or a fiber-transition guard wraps. The
+ * lending state machine ANDs clause 0 (`agent == lender`) in front of it; the debt asset
+ * policy uses it directly as the proof-gated `mintPolicy`.
+ */
+export declare function buildOriginationGuard(refs?: OriginationGuardRefs): JsonLogicRule;
+/**
+ * Construct the eligibility-proof witness the origination guard reads. The `{publicValues,
+ * proof}` come from the SP1 zk-jlvm prover (`--mode groth16`) run over the public rule and the
+ * borrower's PRIVATE data context. Both are lowercase `0x`-hex; they are exposed to the guard
+ * under the reserved `witness` key (on the loan `originate` event payload, or on a proof-gated
+ * `MintAsset`).
+ */
+export declare function buildEligibilityWitness(bundle: Pick<Groth16Bundle, 'publicValues' | 'proof'>): Groth16WitnessMap;