@ottochain/sdk 2.3.0 → 2.5.0

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

@@ -0,0 +1,556 @@
+/**
+ * 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';
+import type { FiberAppDefinition } from '../../schema/fiber-app.js';
+export { lendingZkLoanDef };
+/** All lending state machine definitions. */
+export declare const LENDING_DEFINITIONS: {
+    readonly zkLoan: {
+        readonly metadata: {
+            readonly name: "LendingZkLoan";
+            readonly app: "lending";
+            readonly type: "zkLoan";
+            readonly version: "1.0.0";
+            readonly description: "Privacy-preserving collateralized loan: the borrower proves loan eligibility (collateral coverage / credit-score floor) in zero-knowledge without revealing the financials; collateral, principal and repayment are asset-subsystem tokens driven by the loan lifecycle.";
+            readonly crossReferences: {
+                readonly borrowerIdentityId: "Links to the borrower's IdentityAgent";
+                readonly lenderIdentityId: "Links to the lender's IdentityAgent (loan originator)";
+                readonly collateralAssetId: "Asset instance locked as collateral (held by the loan's escrow fiber)";
+                readonly debtAssetId: "Asset instance representing the outstanding loan principal/debt minted to the borrower";
+            };
+        };
+        readonly createSchema: {
+            readonly required: readonly ["borrower", "lender", "principalAmount", "collateralAssetId", "collateralPolicy", "debtPolicy", "lendingRuleVKey", "lendingRuleLogicHash", "keccakTrue"];
+            readonly properties: {
+                readonly borrower: {
+                    readonly type: "address";
+                    readonly description: "DAG address of the borrower";
+                    readonly immutable: true;
+                };
+                readonly lender: {
+                    readonly type: "address";
+                    readonly description: "DAG address of the lender / loan originator";
+                    readonly immutable: true;
+                };
+                readonly principalAmount: {
+                    readonly type: "integer";
+                    readonly description: "PUBLIC loan principal (asset minor-units). The financials backing eligibility stay private.";
+                    readonly minimum: 1;
+                    readonly immutable: true;
+                };
+                readonly collateralAssetId: {
+                    readonly type: "uuid";
+                    readonly description: "Asset instance id pledged as collateral (its private valuation is never revealed).";
+                    readonly immutable: true;
+                };
+                readonly collateralPolicy: {
+                    readonly type: "string";
+                    readonly description: "Collateral asset policy name (e.g. 'collateral-vault-v1.asset').";
+                    readonly immutable: true;
+                };
+                readonly debtPolicy: {
+                    readonly type: "string";
+                    readonly description: "Debt/loan-token asset policy name (e.g. 'loan-debt-v1.asset').";
+                    readonly immutable: true;
+                };
+                readonly escrowFiberId: {
+                    readonly type: "uuid";
+                    readonly description: "Fiber that custodies the locked collateral (AssetHolder.Fiber). Defaults to this loan fiber.";
+                };
+                readonly lendingRuleVKey: {
+                    readonly type: "hash";
+                    readonly description: "PINNED SP1 program verifying key (bytes32, 0x-hex) for the eligibility circuit.";
+                    readonly immutable: true;
+                };
+                readonly lendingRuleLogicHash: {
+                    readonly type: "hash";
+                    readonly description: "PINNED logicHash of the public lending rule = keccak256(canonicalize(rule)). The proof's committed exprHash must equal this.";
+                    readonly immutable: true;
+                };
+                readonly keccakTrue: {
+                    readonly type: "hash";
+                    readonly description: "PINNED keccak256(canonicalize(true)) — the outputHash a 'rule returned true' proof must commit.";
+                    readonly immutable: true;
+                };
+                readonly dueOrdinal: {
+                    readonly type: "integer";
+                    readonly description: "Optional snapshot ordinal by which repayment is due.";
+                    readonly minimum: 0;
+                };
+            };
+        };
+        readonly stateSchema: {
+            readonly properties: {
+                readonly status: {
+                    readonly type: "string";
+                    readonly computed: true;
+                };
+                readonly borrower: {
+                    readonly type: "address";
+                    readonly immutable: true;
+                };
+                readonly lender: {
+                    readonly type: "address";
+                    readonly immutable: true;
+                };
+                readonly principalAmount: {
+                    readonly type: "integer";
+                    readonly immutable: true;
+                };
+                readonly collateralAssetId: {
+                    readonly type: "uuid";
+                    readonly immutable: true;
+                };
+                readonly collateralPolicy: {
+                    readonly type: "string";
+                    readonly immutable: true;
+                };
+                readonly debtPolicy: {
+                    readonly type: "string";
+                    readonly immutable: true;
+                };
+                readonly escrowFiberId: {
+                    readonly type: "uuid";
+                };
+                readonly debtAssetId: {
+                    readonly type: "uuid";
+                    readonly computed: true;
+                };
+                readonly lendingRuleVKey: {
+                    readonly type: "hash";
+                    readonly immutable: true;
+                };
+                readonly lendingRuleLogicHash: {
+                    readonly type: "hash";
+                    readonly immutable: true;
+                };
+                readonly keccakTrue: {
+                    readonly type: "hash";
+                    readonly immutable: true;
+                };
+                readonly dueOrdinal: {
+                    readonly type: "integer";
+                };
+                readonly lockedAt: {
+                    readonly type: "integer";
+                    readonly computed: true;
+                };
+                readonly originatedAt: {
+                    readonly type: "integer";
+                    readonly computed: true;
+                };
+                readonly repaidAt: {
+                    readonly type: "integer";
+                    readonly computed: true;
+                };
+                readonly defaultedAt: {
+                    readonly type: "integer";
+                    readonly computed: true;
+                };
+                readonly liquidatedAt: {
+                    readonly type: "integer";
+                    readonly computed: true;
+                };
+            };
+        };
+        readonly eventSchemas: {
+            readonly lock_collateral: {
+                readonly description: "Borrower locks the pledged collateral asset into the loan escrow fiber (drives an asset Transfer/Mint into AssetHolder.Fiber).";
+            };
+            readonly originate: {
+                readonly description: "Lender originates the loan after the borrower's zk eligibility proof verifies. The witness carries the SP1-Groth16 {publicValues, proof}; the guard binds them to the pinned public lending rule. The effect mints the debt/principal asset to the borrower.";
+                readonly required: readonly ["witness", "debtAssetId"];
+                readonly properties: {
+                    readonly witness: {
+                        readonly type: "object";
+                        readonly description: "Eligibility-proof witness: { publicValues: 0x-hex, proof: 0x-hex }. Exposed to the guard under the reserved `witness` key.";
+                        readonly properties: {
+                            readonly publicValues: {
+                                readonly type: "string";
+                                readonly description: "abi_encode(JlvmPublicValues), 0x-hex.";
+                            };
+                            readonly proof: {
+                                readonly type: "string";
+                                readonly description: "SP1-Groth16 proof bytes, 0x-hex.";
+                            };
+                        };
+                        readonly required: readonly ["publicValues", "proof"];
+                    };
+                    readonly debtAssetId: {
+                        readonly type: "uuid";
+                        readonly description: "Asset instance id for the debt/principal token minted to the borrower.";
+                    };
+                };
+            };
+            readonly repay: {
+                readonly description: "Borrower repays the principal (drives a Burn of the debt token); on success the collateral is released back to the borrower via the escrow fiber.";
+            };
+            readonly default_loan: {
+                readonly description: "Mark the loan defaulted once past due (drives the collateral toward liquidation).";
+            };
+            readonly liquidate: {
+                readonly description: "Lender liquidates a defaulted loan: the locked collateral is transferred to the lender via the escrow fiber.";
+            };
+            readonly cancel: {
+                readonly description: "Cancel a loan request before collateral is locked.";
+                readonly properties: {
+                    readonly reason: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly states: {
+            readonly REQUESTED: {
+                readonly id: "REQUESTED";
+                readonly isFinal: false;
+                readonly metadata: {
+                    readonly label: "Requested";
+                    readonly description: "Loan requested; collateral not yet locked, eligibility not yet proven.";
+                    readonly category: "initial";
+                };
+            };
+            readonly COLLATERAL_LOCKED: {
+                readonly id: "COLLATERAL_LOCKED";
+                readonly isFinal: false;
+                readonly metadata: {
+                    readonly label: "Collateral Locked";
+                    readonly description: "Collateral asset escrowed in the loan fiber; awaiting the lender's zk-gated origination.";
+                    readonly category: "pending";
+                };
+            };
+            readonly ACTIVE: {
+                readonly id: "ACTIVE";
+                readonly isFinal: false;
+                readonly metadata: {
+                    readonly label: "Active";
+                    readonly description: "Loan originated (eligibility proven in zk); principal minted to the borrower.";
+                    readonly category: "active";
+                };
+            };
+            readonly DEFAULTED: {
+                readonly id: "DEFAULTED";
+                readonly isFinal: false;
+                readonly metadata: {
+                    readonly label: "Defaulted";
+                    readonly description: "Loan past due and unpaid; collateral pending liquidation.";
+                    readonly category: "pending";
+                };
+            };
+            readonly REPAID: {
+                readonly id: "REPAID";
+                readonly isFinal: true;
+                readonly metadata: {
+                    readonly label: "Repaid";
+                    readonly description: "Principal repaid (debt burned) and collateral released to the borrower.";
+                    readonly category: "terminal";
+                };
+            };
+            readonly LIQUIDATED: {
+                readonly id: "LIQUIDATED";
+                readonly isFinal: true;
+                readonly metadata: {
+                    readonly label: "Liquidated";
+                    readonly description: "Defaulted loan settled by transferring the collateral to the lender.";
+                    readonly category: "terminal";
+                };
+            };
+            readonly CANCELLED: {
+                readonly id: "CANCELLED";
+                readonly isFinal: true;
+                readonly metadata: {
+                    readonly label: "Cancelled";
+                    readonly description: "Loan request cancelled before any collateral was locked.";
+                    readonly category: "terminal";
+                };
+            };
+        };
+        readonly initialState: "REQUESTED";
+        readonly transitions: readonly [{
+            readonly from: "REQUESTED";
+            readonly to: "COLLATERAL_LOCKED";
+            readonly eventName: "lock_collateral";
+            readonly guard: {
+                readonly and: readonly [{
+                    readonly in: readonly [{
+                        readonly var: "state.borrower";
+                    }, {
+                        readonly map: readonly [{
+                            readonly var: "proofs";
+                        }, {
+                            readonly var: "address";
+                        }];
+                    }];
+                }, {
+                    readonly '===': readonly [{
+                        readonly var: "event.assetId";
+                    }, {
+                        readonly var: "state.collateralAssetId";
+                    }];
+                }];
+            };
+            readonly effect: {
+                readonly merge: readonly [{
+                    readonly var: "state";
+                }, {
+                    readonly status: "COLLATERAL_LOCKED";
+                    readonly lockedAt: {
+                        readonly var: "$ordinal";
+                    };
+                }];
+            };
+            readonly dependencies: readonly [];
+        }, {
+            readonly from: "REQUESTED";
+            readonly to: "CANCELLED";
+            readonly eventName: "cancel";
+            readonly guard: {
+                readonly or: readonly [{
+                    readonly in: readonly [{
+                        readonly var: "state.borrower";
+                    }, {
+                        readonly map: readonly [{
+                            readonly var: "proofs";
+                        }, {
+                            readonly var: "address";
+                        }];
+                    }];
+                }, {
+                    readonly in: readonly [{
+                        readonly var: "state.lender";
+                    }, {
+                        readonly map: readonly [{
+                            readonly var: "proofs";
+                        }, {
+                            readonly var: "address";
+                        }];
+                    }];
+                }];
+            };
+            readonly effect: {
+                readonly merge: readonly [{
+                    readonly var: "state";
+                }, {
+                    readonly status: "CANCELLED";
+                    readonly cancelledAt: {
+                        readonly var: "$ordinal";
+                    };
+                    readonly reason: {
+                        readonly var: "event.reason";
+                    };
+                }];
+            };
+            readonly dependencies: readonly [];
+        }, {
+            readonly from: "COLLATERAL_LOCKED";
+            readonly to: "ACTIVE";
+            readonly eventName: "originate";
+            readonly guard: {
+                readonly and: readonly [{
+                    readonly in: readonly [{
+                        readonly var: "state.lender";
+                    }, {
+                        readonly map: readonly [{
+                            readonly var: "proofs";
+                        }, {
+                            readonly var: "address";
+                        }];
+                    }];
+                }, {
+                    readonly groth16_verify: readonly [{
+                        readonly var: "state.lendingRuleVKey";
+                    }, {
+                        readonly var: "event.witness.publicValues";
+                    }, {
+                        readonly var: "event.witness.proof";
+                    }];
+                }, {
+                    readonly '===': readonly [{
+                        readonly cat: readonly ["0x", {
+                            readonly substr: readonly [{
+                                readonly var: "event.witness.publicValues";
+                            }, 2, 64];
+                        }];
+                    }, {
+                        readonly var: "state.lendingRuleLogicHash";
+                    }];
+                }, {
+                    readonly '===': readonly [{
+                        readonly cat: readonly ["0x", {
+                            readonly substr: readonly [{
+                                readonly var: "event.witness.publicValues";
+                            }, 130, 64];
+                        }];
+                    }, {
+                        readonly var: "state.keccakTrue";
+                    }];
+                }, {
+                    readonly '===': readonly [{
+                        readonly substr: readonly [{
+                            readonly var: "event.witness.publicValues";
+                        }, 256, 2];
+                    }, "01"];
+                }];
+            };
+            readonly effect: {
+                readonly merge: readonly [{
+                    readonly var: "state";
+                }, {
+                    readonly status: "ACTIVE";
+                    readonly originatedAt: {
+                        readonly var: "$ordinal";
+                    };
+                    readonly debtAssetId: {
+                        readonly var: "event.debtAssetId";
+                    };
+                }];
+            };
+            readonly dependencies: readonly [];
+        }, {
+            readonly from: "ACTIVE";
+            readonly to: "REPAID";
+            readonly eventName: "repay";
+            readonly guard: {
+                readonly in: readonly [{
+                    readonly var: "state.borrower";
+                }, {
+                    readonly map: readonly [{
+                        readonly var: "proofs";
+                    }, {
+                        readonly var: "address";
+                    }];
+                }];
+            };
+            readonly effect: {
+                readonly merge: readonly [{
+                    readonly var: "state";
+                }, {
+                    readonly status: "REPAID";
+                    readonly repaidAt: {
+                        readonly var: "$ordinal";
+                    };
+                    readonly _transferAsset: readonly [{
+                        readonly assetId: {
+                            readonly var: "state.collateralAssetId";
+                        };
+                        readonly recipient: {
+                            readonly Wallet: {
+                                readonly address: {
+                                    readonly var: "state.borrower";
+                                };
+                            };
+                        };
+                    }];
+                }];
+            };
+            readonly dependencies: readonly [];
+        }, {
+            readonly from: "ACTIVE";
+            readonly to: "DEFAULTED";
+            readonly eventName: "default_loan";
+            readonly guard: {
+                readonly and: readonly [{
+                    readonly var: "state.dueOrdinal";
+                }, {
+                    readonly '>=': readonly [{
+                        readonly var: "$ordinal";
+                    }, {
+                        readonly var: "state.dueOrdinal";
+                    }];
+                }];
+            };
+            readonly effect: {
+                readonly merge: readonly [{
+                    readonly var: "state";
+                }, {
+                    readonly status: "DEFAULTED";
+                    readonly defaultedAt: {
+                        readonly var: "$ordinal";
+                    };
+                }];
+            };
+            readonly dependencies: readonly [];
+        }, {
+            readonly from: "DEFAULTED";
+            readonly to: "LIQUIDATED";
+            readonly eventName: "liquidate";
+            readonly guard: {
+                readonly in: readonly [{
+                    readonly var: "state.lender";
+                }, {
+                    readonly map: readonly [{
+                        readonly var: "proofs";
+                    }, {
+                        readonly var: "address";
+                    }];
+                }];
+            };
+            readonly effect: {
+                readonly merge: readonly [{
+                    readonly var: "state";
+                }, {
+                    readonly status: "LIQUIDATED";
+                    readonly liquidatedAt: {
+                        readonly var: "$ordinal";
+                    };
+                    readonly _transferAsset: readonly [{
+                        readonly assetId: {
+                            readonly var: "state.collateralAssetId";
+                        };
+                        readonly recipient: {
+                            readonly Wallet: {
+                                readonly address: {
+                                    readonly var: "state.lender";
+                                };
+                            };
+                        };
+                    }];
+                }];
+            };
+            readonly dependencies: readonly [];
+        }];
+    };
+};
+export type LendingType = keyof typeof LENDING_DEFINITIONS;
+/**
+ * Get a lending state machine definition by type.
+ * @param type - 'zkLoan' (default: 'zkLoan')
+ */
+export declare function getLendingDefinition(type?: LendingType): FiberAppDefinition;
+export { lendingRule, pinLendingRule, buildOriginationGuard, buildEligibilityWitness, type LendingRuleParams, type PinnedLendingRule, type OriginationGuardRefs, type JsonLogicRule, } from './eligibility.js';
+export { reputationScore, reputationCreditRule, buildCreditDataContext, reputationAuthorityClause, type CreditScoreConfig, type ReputationCreditParams, type CreditDataContext, } from './credit-scoring.js';
+export { walletHolder, fiberHolder, behaviorBits, TokenBehaviors, type AssetHolder, type TokenBehavior, type SupplyPolicy, type MorphismKind, type MorphismVisibility, type MorphismSpec, type VersionReq, type PolicyRef, createAssetPolicyPayload, createMintAssetPayload, createApplyMorphismPayload, createAuthorizeComposePayload, type CreateAssetPolicyParams, type CreateAssetPolicyMessage, type MintAssetParams, type MintAssetMessage, type ApplyMorphismParams, type ApplyMorphismMessage, type AuthorizeComposeParams, type AuthorizeComposeMessage, collateralPolicy, debtPolicy, lockCollateralOp, mintPrincipalOp, repayBurnOp, settleCollateralOp, } from './assets.js';

package/dist/types/apps/lending/state-machines/index.d.ts

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