@ottochain/sdk 2.3.0 → 2.4.0

package/dist/esm/apps/lending/assets.js

@@ -0,0 +1,207 @@
+/**
+ * Asset-subsystem integration for the lending family.
+ *
+ * The loan's collateral, principal/debt, and repayment are ASSETS. This module provides
+ * typed payload builders for the OttoChain asset operations and loan-specific helpers that
+ * map the zk-loan lifecycle onto typed asset morphisms.
+ *
+ * Wire shapes mirror the asset-model proposal
+ * (`/home/euler/repos/ottochain/docs/proposals/asset-model.md` §7 — `CreateAssetPolicy`,
+ * `MintAsset`, `ApplyMorphism`, `AuthorizeCompose`; §8 — Governed/ZkVerify-gated morphisms)
+ * and follow the SDK's existing single-key-wrapper convention (the discriminator is the outer
+ * key, e.g. `{ MintAsset: {...} }`), matching `src/ottochain/transaction.ts`
+ * (`createTransitionPayload`, `createScriptPayload`, ...). The asset op-codes are not yet a
+ * merged TypeScript SDK surface; these builders let the lending app construct the proposed
+ * wire format today and sign it with the existing `signTransaction` path.
+ *
+ * Amounts are `Long` on-chain; modeled here as `number` for SDK ergonomics (callers may pass a
+ * string for values beyond 2^53 — the field is serialized verbatim).
+ */
+/** Helpers for the two-variant holder. */
+export const walletHolder = (address) => ({ Wallet: { address } });
+export const fiberHolder = (fiberId) => ({ Fiber: { fiberId } });
+/** Pack a {@link TokenBehavior} to its 5-bit integer (T=16 S=8 C=4 E=2 G=1). */
+export function behaviorBits(b) {
+    return ((b.transferable ? 16 : 0) |
+        (b.splittable ? 8 : 0) |
+        (b.combinable ? 4 : 0) |
+        (b.expirable ? 2 : 0) |
+        (b.governable ? 1 : 0));
+}
+/** Common behavior presets (asset-model.md §2). */
+export const TokenBehaviors = {
+    /** Non-transferable, non-divisible (bits 0). */
+    Soulbound: { transferable: false, splittable: false, combinable: false, expirable: false, governable: false },
+    /** Transferable only (bits 16). */
+    NFT: { transferable: true, splittable: false, combinable: false, expirable: false, governable: false },
+    /** Transferable + splittable + combinable (bits 28 = TSC). */
+    Fungible: { transferable: true, splittable: true, combinable: true, expirable: false, governable: false },
+    /** Fungible + governable (bits 29 = TSCG) — the default for a gated debt token. */
+    GovernedFungible: { transferable: true, splittable: true, combinable: true, expirable: false, governable: true },
+};
+/** Publish an asset policy package version. asset-model.md §7. */
+export function createAssetPolicyPayload(params) {
+    return {
+        CreateAssetPolicy: {
+            name: params.name,
+            version: params.version,
+            behavior: params.behavior,
+            supply: params.supply,
+            morphisms: params.morphisms,
+            stateShape: params.stateShape,
+            ...(params.metadata ? { metadata: params.metadata } : {}),
+        },
+    };
+}
+/**
+ * Mint an asset instance. asset-model.md §7. When the policy's `mintPolicy` is a
+ * `groth16_verify` guard (proof-gated mint), pass the eligibility `witness`.
+ */
+export function createMintAssetPayload(params) {
+    return {
+        MintAsset: {
+            assetId: params.assetId,
+            policyRef: params.policyRef,
+            holder: params.holder,
+            amount: params.amount,
+            ...(params.expiresAt !== undefined ? { expiresAt: params.expiresAt } : {}),
+            ...(params.witness ? { witness: params.witness } : {}),
+        },
+    };
+}
+/**
+ * Apply a typed morphism (Transfer / Burn / Compose / ...). asset-model.md §7.
+ * Transfer = `{ kind: "Transfer", recipient }`; Burn (repay) = `{ kind: "Burn" }`.
+ */
+export function createApplyMorphismPayload(params) {
+    return {
+        ApplyMorphism: {
+            assetId: params.assetId,
+            kind: params.kind,
+            targetSequenceNumber: params.targetSequenceNumber,
+            ...(params.recipient ? { recipient: params.recipient } : {}),
+            ...(params.otherAssets ? { otherAssets: params.otherAssets } : {}),
+            ...(params.compositeId ? { compositeId: params.compositeId } : {}),
+            ...(params.shardIds ? { shardIds: params.shardIds } : {}),
+            ...(params.nonce !== undefined ? { nonce: params.nonce } : {}),
+            ...(params.witness ? { witness: params.witness } : {}),
+        },
+    };
+}
+/** Commit half of a two-party compose. asset-model.md §7/§8. */
+export function createAuthorizeComposePayload(params) {
+    return {
+        AuthorizeCompose: {
+            assetId: params.assetId,
+            partnerPolicy: params.partnerPolicy,
+            nonce: params.nonce,
+            expiresAt: params.expiresAt,
+            targetSequenceNumber: params.targetSequenceNumber,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Loan-specific asset policy builders
+// ---------------------------------------------------------------------------
+/**
+ * The collateral vault policy: an NFT-like custodial holding (no fungible split) whose
+ * `Transfer` morphism is Governed — the loan/escrow fiber is the authorization. Locking is
+ * a custody Transfer into `AssetHolder.Fiber(escrow)`; release/liquidation is a Transfer out
+ * driven by the loan fiber's REPAID / LIQUIDATED transition (`_transferAsset`).
+ */
+export function collateralPolicy(name = "collateral-vault-v1.asset", version = "1.0.0") {
+    return {
+        name,
+        version,
+        behavior: { transferable: true, splittable: false, combinable: false, expirable: false, governable: true },
+        supply: { maxSupply: null, mintPolicy: null, burnPolicy: null, decimals: 0 },
+        morphisms: {
+            Transfer: { visibility: "Governed" },
+            Burn: { visibility: "Disabled" },
+            Compose: { visibility: "Disabled" },
+        },
+        stateShape: {},
+        metadata: { family: "lending", role: "collateral" },
+    };
+}
+/**
+ * The loan-debt / principal policy: a governed fungible whose `mintPolicy` is the
+ * proof-gated origination guard — the principal is mintable to the borrower only when the
+ * eligibility proof verifies. Repayment is a `Burn` governed by `burnPolicy`.
+ *
+ * @param mintGuard the origination guard (see `buildOriginationGuard`) — a `groth16_verify`
+ *   expression bound to the pinned public lending rule.
+ */
+export function debtPolicy(mintGuard, name = "loan-debt-v1.asset", version = "1.0.0") {
+    return {
+        name,
+        version,
+        behavior: TokenBehaviors.GovernedFungible,
+        supply: {
+            maxSupply: null,
+            // Proof-gated mint: principal is minted only if the eligibility proof verifies.
+            mintPolicy: mintGuard,
+            // Repayment burns the debt; only the holder (borrower) may burn theirs. The asset context has
+            // no `event` key — bind to the verified `signers` (chain-derived from the op's proofs).
+            burnPolicy: { in: [{ var: "holder.Wallet.address" }, { var: "signers" }] },
+            decimals: 2,
+        },
+        morphisms: {
+            Transfer: { visibility: "Public" },
+            Burn: { visibility: "Public" },
+        },
+        stateShape: {},
+        metadata: { family: "lending", role: "debt" },
+    };
+}
+// ---------------------------------------------------------------------------
+// Loan lifecycle → asset morphism drivers
+// ---------------------------------------------------------------------------
+/**
+ * lock_collateral: custody Transfer of the pledged collateral into the loan escrow fiber.
+ * (asset-model.md §10 — locking is a custody transfer to `AssetHolder.Fiber`, there is no
+ * `Lock` morphism.)
+ */
+export function lockCollateralOp(args) {
+    return createApplyMorphismPayload({
+        assetId: args.collateralAssetId,
+        kind: "Transfer",
+        recipient: fiberHolder(args.escrowFiberId),
+        targetSequenceNumber: args.targetSequenceNumber,
+    });
+}
+/**
+ * originate: Mint the loan principal/debt to the borrower. The policy's `mintPolicy`
+ * (the origination guard) reads the eligibility `witness` ({publicValues, proof}).
+ */
+export function mintPrincipalOp(args) {
+    return createMintAssetPayload({
+        assetId: args.debtAssetId,
+        policyRef: args.debtPolicyRef,
+        holder: walletHolder(args.borrower),
+        amount: args.principalAmount,
+        witness: args.witness,
+    });
+}
+/** repay: Burn the borrower's debt token (the principal is repaid). */
+export function repayBurnOp(args) {
+    return createApplyMorphismPayload({
+        assetId: args.debtAssetId,
+        kind: "Burn",
+        targetSequenceNumber: args.targetSequenceNumber,
+    });
+}
+/**
+ * release / liquidate: Transfer the escrowed collateral out of the escrow fiber to a
+ * recipient (the borrower on REPAID, the lender on LIQUIDATED). On-chain this is emitted by
+ * the loan fiber's transition via `_transferAsset`; this builder produces the equivalent
+ * explicit `ApplyMorphism(Transfer)` for off-fiber/manual settlement.
+ */
+export function settleCollateralOp(args) {
+    return createApplyMorphismPayload({
+        assetId: args.collateralAssetId,
+        kind: "Transfer",
+        recipient: walletHolder(args.recipient),
+        targetSequenceNumber: args.targetSequenceNumber,
+    });
+}

package/dist/esm/apps/lending/credit-scoring.js

@@ -0,0 +1,81 @@
+/**
+ * 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 { DEFAULT_REPUTATION_CONFIG, } from "../identity/index.js";
+import { lendingRule } from "./eligibility.js";
+/**
+ * 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 function reputationScore(attestations, config = DEFAULT_REPUTATION_CONFIG) {
+    const raw = attestations.reduce((sum, a) => sum + (a.delta ?? 0), config.baseReputation);
+    return Math.max(config.minReputation, raw);
+}
+/**
+ * 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 function reputationCreditRule(params) {
+    const base = lendingRule(params); // coverage, or {and:[coverage, creditScore floor]}
+    const subjectBound = { "===": [{ var: "subject" }, params.borrowerId] };
+    const clauses = "and" in base ? base.and : [base];
+    return { and: [...clauses, subjectBound] };
+}
+/**
+ * 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 function buildCreditDataContext(args) {
+    return {
+        collateralValue: args.collateralValue,
+        creditScore: reputationScore(args.attestations, args.config ?? DEFAULT_REPUTATION_CONFIG),
+        subject: args.borrowerId,
+    };
+}
+/**
+ * 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 function reputationAuthorityClause(authorityPubKey) {
+    return {
+        schnorr_verify: [
+            authorityPubKey, // the reputation authority's public key — PINNED literal, not witness-supplied
+            { var: "scoreCommit" }, // the signed message: a commitment over (subject, creditScore)
+            { var: "repSig" }, // the authority's signature over scoreCommit
+        ],
+    };
+}

package/dist/esm/apps/lending/eligibility.js

@@ -0,0 +1,115 @@
+/**
+ * The eligibility-proof model for the zk-loan: pin a PUBLIC lending rule, build the
+ * semi-private origination guard that gates it, and construct the witness the guard reads.
+ *
+ * The borrower proves in zero-knowledge that their PRIVATE financials satisfy the PUBLIC
+ * lending rule — without revealing them. The rule (with its literal bounds) is canonicalized
+ * and keccak-hashed into a `logicHash`; the proof commits that same `exprHash`, so binding
+ * `exprHash == logicHash` pins exactly WHICH rule was proven. See `src/zk` and
+ * `/home/euler/repos/ottochain/docs/proposals/asset-model.md` §8 (ZkVerify-gated morphisms).
+ */
+import { exprHash, KECCAK_TRUE } from "../../zk/index.js";
+/**
+ * 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 function lendingRule(params) {
+    const coverage = {
+        ">=": [
+            { "*": [{ var: "collateralValue" }, 100] },
+            params.loanAmount * params.collateralRatioPct,
+        ],
+    };
+    if (params.minCreditScore === undefined) {
+        return coverage;
+    }
+    return {
+        and: [
+            coverage,
+            { ">=": [{ var: "creditScore" }, params.minCreditScore] },
+        ],
+    };
+}
+/**
+ * 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 function pinLendingRule(params, vkey) {
+    const rule = lendingRule(params);
+    return {
+        rule,
+        logicHash: exprHash(rule),
+        keccakTrue: KECCAK_TRUE,
+        vkey,
+    };
+}
+/**
+ * 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 function buildOriginationGuard(refs = {}) {
+    const vkeyVar = refs.vkeyVar ?? "state.lendingRuleVKey";
+    const logicHashVar = refs.logicHashVar ?? "state.lendingRuleLogicHash";
+    const keccakTrueVar = refs.keccakTrueVar ?? "state.keccakTrue";
+    return {
+        and: [
+            {
+                groth16_verify: [
+                    { var: vkeyVar },
+                    { var: "witness.publicValues" },
+                    { var: "witness.proof" },
+                ],
+            },
+            {
+                "===": [
+                    { cat: ["0x", { substr: [{ var: "witness.publicValues" }, 2, 64] }] },
+                    { var: logicHashVar },
+                ],
+            },
+            {
+                "===": [
+                    { cat: ["0x", { substr: [{ var: "witness.publicValues" }, 130, 64] }] },
+                    { var: keccakTrueVar },
+                ],
+            },
+            {
+                "===": [{ substr: [{ var: "witness.publicValues" }, 256, 2] }, "01"],
+            },
+        ],
+    };
+}
+/**
+ * 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 function buildEligibilityWitness(bundle) {
+    return {
+        publicValues: bundle.publicValues,
+        proof: bundle.proof,
+    };
+}

package/dist/esm/apps/lending/index.js

@@ -0,0 +1,69 @@
+/**
+ * Lending Application — privacy-preserving credit & lending on OttoChain.
+ *
+ * The lending family hosts private-finance fibers whose financial state stays private while
+ * eligibility is proven in zero-knowledge. The collateral, principal, and repayment are
+ * asset-subsystem tokens driven by the fiber lifecycle.
+ *
+ * Variants:
+ *   - `zkLoan` — a collateralized loan whose origination is gated by a zk eligibility proof
+ *     (collateral coverage / credit-score floor) without revealing the borrower's financials.
+ *
+ * The name `lending` (vs. `loans`) deliberately generalizes for the future credit family —
+ * credit lines, BNPL, bonds, escrowed credit — mirroring how `markets` hosts prediction /
+ * auction / crowdfund variants under one app.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getLendingDefinition,
+ *   pinLendingRule,
+ *   buildOriginationGuard,
+ *   buildEligibilityWitness,
+ *   debtPolicy,
+ *   collateralPolicy,
+ * } from '@ottochain/sdk/apps/lending';
+ *
+ * const loanDef = getLendingDefinition('zkLoan');
+ *
+ * // Pin the public rule + build the proof-gated origination guard.
+ * const pinned = pinLendingRule({ collateralRatioPct: 150, loanAmount: 1000, minCreditScore: 680 }, vkey);
+ * const guard = buildOriginationGuard();
+ * const debt = debtPolicy(guard);
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { lendingZkLoanDef } from "./state-machines/index.js";
+export { lendingZkLoanDef };
+/** All lending state machine definitions. */
+export const LENDING_DEFINITIONS = {
+    zkLoan: lendingZkLoanDef,
+};
+/**
+ * Get a lending state machine definition by type.
+ * @param type - 'zkLoan' (default: 'zkLoan')
+ */
+export function getLendingDefinition(type = "zkLoan") {
+    return LENDING_DEFINITIONS[type];
+}
+// ---------------------------------------------------------------------------
+// Eligibility-proof model (the semi-private gate)
+// ---------------------------------------------------------------------------
+export { lendingRule, pinLendingRule, buildOriginationGuard, buildEligibilityWitness, } from "./eligibility.js";
+// ---------------------------------------------------------------------------
+// Credit scoring via the identity + reputation app (the creditScore IS reputation)
+// ---------------------------------------------------------------------------
+export { reputationScore, reputationCreditRule, buildCreditDataContext, reputationAuthorityClause, } from "./credit-scoring.js";
+// ---------------------------------------------------------------------------
+// Asset-subsystem integration (collateral, debt/principal, repayment morphisms)
+// ---------------------------------------------------------------------------
+export { 
+// value types
+walletHolder, fiberHolder, behaviorBits, TokenBehaviors, 
+// op payload builders
+createAssetPolicyPayload, createMintAssetPayload, createApplyMorphismPayload, createAuthorizeComposePayload, 
+// loan policy builders
+collateralPolicy, debtPolicy, 
+// lifecycle → morphism drivers
+lockCollateralOp, mintPrincipalOp, repayBurnOp, settleCollateralOp, } from "./assets.js";

package/dist/esm/apps/lending/state-machines/index.js

@@ -0,0 +1,5 @@
+/**
+ * Lending state machine definitions.
+ * Re-exports from TypeScript definition files.
+ */
+export { lendingZkLoanDef } from './lending-zk-loan.js';