@ottochain/sdk 2.3.0 → 2.4.0

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

@@ -0,0 +1,258 @@
+/**
+ * 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).
+ */
+/** A holder of an asset: a wallet address, or a custody fiber (the escrow). */
+export type AssetHolder = {
+    Wallet: {
+        address: string;
+    };
+} | {
+    Fiber: {
+        fiberId: string;
+    };
+};
+/** Helpers for the two-variant holder. */
+export declare const walletHolder: (address: string) => AssetHolder;
+export declare const fiberHolder: (fiberId: string) => AssetHolder;
+/** 5-bit token behavior lattice (T/S/C ascending, E/G descending). asset-model.md §2. */
+export interface TokenBehavior {
+    transferable: boolean;
+    splittable: boolean;
+    combinable: boolean;
+    expirable: boolean;
+    governable: boolean;
+}
+/** Pack a {@link TokenBehavior} to its 5-bit integer (T=16 S=8 C=4 E=2 G=1). */
+export declare function behaviorBits(b: TokenBehavior): number;
+/** Common behavior presets (asset-model.md §2). */
+export declare const TokenBehaviors: {
+    /** Non-transferable, non-divisible (bits 0). */
+    readonly Soulbound: TokenBehavior;
+    /** Transferable only (bits 16). */
+    readonly NFT: TokenBehavior;
+    /** Transferable + splittable + combinable (bits 28 = TSC). */
+    readonly Fungible: TokenBehavior;
+    /** Fungible + governable (bits 29 = TSCG) — the default for a gated debt token. */
+    readonly GovernedFungible: TokenBehavior;
+};
+/** A JSON-Logic expression (guard/policy). */
+export type JsonLogicRule = Record<string, unknown>;
+/** Supply policy: cap, mint/burn JSON-Logic guards, decimals. asset-model.md §3. */
+export interface SupplyPolicy {
+    /** Hard cap; null = uncapped. */
+    maxSupply?: number | string | null;
+    /** Mint guard (JSON-Logic); null = minting closed after genesis. */
+    mintPolicy?: JsonLogicRule | null;
+    /** Burn guard (JSON-Logic); null = no burning. */
+    burnPolicy?: JsonLogicRule | null;
+    /** Fungible decimals; null/0 for NFTs. */
+    decimals?: number | null;
+}
+/** Morphism kinds. asset-model.md §4. */
+export type MorphismKind = "Transfer" | "Burn" | "Fractionalize" | "Compose" | "Decompose" | "Wrap" | "Stake";
+/** Morphism visibility — Governed carries a JSON-Logic guard. asset-model.md §8. */
+export type MorphismVisibility = "Public" | "Governed" | "Disabled";
+/** Per-kind morphism spec on a policy version. asset-model.md §7. */
+export interface MorphismSpec {
+    visibility: MorphismVisibility;
+    /** Counter-party policy allowlist; omit for any. */
+    allowedPolicies?: string[];
+    /** Counter-party behavior-bitmask allowlist; omit for any. */
+    allowedTypes?: number[];
+    /** JSON-Logic guard (Governed only). */
+    guard?: JsonLogicRule;
+}
+/** A version requirement for resolving a policy. mirrors SDK `VersionReq`. */
+export type VersionReq = {
+    Exact: {
+        version: string;
+    };
+} | {
+    Caret: {
+        version: string;
+    };
+} | {
+    Tilde: {
+        version: string;
+    };
+} | {
+    Latest: Record<string, never>;
+} | {
+    PinnedHash: {
+        hash: string;
+    };
+};
+/** A policy reference `(name, versionReq)`. mirrors SDK `SchemaRef`. */
+export interface PolicyRef {
+    name: string;
+    version: VersionReq;
+}
+export interface CreateAssetPolicyParams {
+    /** `.asset` registry name, e.g. "collateral-vault-v1.asset". */
+    name: string;
+    version: string;
+    behavior: TokenBehavior;
+    supply: SupplyPolicy;
+    morphisms: Partial<Record<MorphismKind, MorphismSpec>>;
+    /** The asset record's state shape (proto message shape); free-form here. */
+    stateShape: Record<string, unknown>;
+    metadata?: Record<string, string>;
+}
+export interface CreateAssetPolicyMessage {
+    CreateAssetPolicy: {
+        name: string;
+        version: string;
+        behavior: TokenBehavior;
+        supply: SupplyPolicy;
+        morphisms: Partial<Record<MorphismKind, MorphismSpec>>;
+        stateShape: Record<string, unknown>;
+        metadata?: Record<string, string>;
+    };
+}
+/** Publish an asset policy package version. asset-model.md §7. */
+export declare function createAssetPolicyPayload(params: CreateAssetPolicyParams): CreateAssetPolicyMessage;
+export interface MintAssetParams {
+    /** The new asset instance id (UUID). */
+    assetId: string;
+    policyRef: PolicyRef;
+    holder: AssetHolder;
+    amount: number | string;
+    expiresAt?: number;
+    /** Witness the policy's `mintPolicy` guard reads (e.g. a Groth16 eligibility proof). */
+    witness?: Record<string, unknown>;
+}
+export interface MintAssetMessage {
+    MintAsset: {
+        assetId: string;
+        policyRef: PolicyRef;
+        holder: AssetHolder;
+        amount: number | string;
+        expiresAt?: number;
+        witness?: Record<string, unknown>;
+    };
+}
+/**
+ * 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 declare function createMintAssetPayload(params: MintAssetParams): MintAssetMessage;
+export interface ApplyMorphismParams {
+    assetId: string;
+    kind: MorphismKind;
+    targetSequenceNumber: number;
+    recipient?: AssetHolder;
+    otherAssets?: string[];
+    compositeId?: string;
+    shardIds?: string[];
+    nonce?: number;
+    /** Witness a Governed morphism's `guard` reads. */
+    witness?: Record<string, unknown>;
+}
+export interface ApplyMorphismMessage {
+    ApplyMorphism: {
+        assetId: string;
+        kind: MorphismKind;
+        targetSequenceNumber: number;
+        recipient?: AssetHolder;
+        otherAssets?: string[];
+        compositeId?: string;
+        shardIds?: string[];
+        nonce?: number;
+        witness?: Record<string, unknown>;
+    };
+}
+/**
+ * Apply a typed morphism (Transfer / Burn / Compose / ...). asset-model.md §7.
+ * Transfer = `{ kind: "Transfer", recipient }`; Burn (repay) = `{ kind: "Burn" }`.
+ */
+export declare function createApplyMorphismPayload(params: ApplyMorphismParams): ApplyMorphismMessage;
+export interface AuthorizeComposeParams {
+    assetId: string;
+    partnerPolicy: string;
+    nonce: number;
+    expiresAt: number;
+    targetSequenceNumber: number;
+}
+export interface AuthorizeComposeMessage {
+    AuthorizeCompose: {
+        assetId: string;
+        partnerPolicy: string;
+        nonce: number;
+        expiresAt: number;
+        targetSequenceNumber: number;
+    };
+}
+/** Commit half of a two-party compose. asset-model.md §7/§8. */
+export declare function createAuthorizeComposePayload(params: AuthorizeComposeParams): AuthorizeComposeMessage;
+/**
+ * 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 declare function collateralPolicy(name?: string, version?: string): CreateAssetPolicyParams;
+/**
+ * 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 declare function debtPolicy(mintGuard: JsonLogicRule, name?: string, version?: string): CreateAssetPolicyParams;
+/**
+ * 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 declare function lockCollateralOp(args: {
+    collateralAssetId: string;
+    escrowFiberId: string;
+    targetSequenceNumber: number;
+}): ApplyMorphismMessage;
+/**
+ * originate: Mint the loan principal/debt to the borrower. The policy's `mintPolicy`
+ * (the origination guard) reads the eligibility `witness` ({publicValues, proof}).
+ */
+export declare function mintPrincipalOp(args: {
+    debtAssetId: string;
+    debtPolicyRef: PolicyRef;
+    borrower: string;
+    principalAmount: number | string;
+    witness: {
+        publicValues: string;
+        proof: string;
+    };
+}): MintAssetMessage;
+/** repay: Burn the borrower's debt token (the principal is repaid). */
+export declare function repayBurnOp(args: {
+    debtAssetId: string;
+    targetSequenceNumber: number;
+}): ApplyMorphismMessage;
+/**
+ * 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 declare function settleCollateralOp(args: {
+    collateralAssetId: string;
+    recipient: string;
+    targetSequenceNumber: number;
+}): ApplyMorphismMessage;

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;