@ottochain/sdk 2.3.0 → 2.4.0

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

@@ -0,0 +1,528 @@
+/**
+ * Privacy-preserving zk-loan — a private-finance lending fiber modeled on Midnight's
+ * zkLoan example, integrated with OttoChain's asset subsystem.
+ *
+ * The borrower proves, in zero-knowledge, that their PRIVATE financials satisfy the
+ * PUBLIC lending rule (collateral coverage and/or a credit-score floor) WITHOUT
+ * revealing the financials. The lender originates the loan. The collateral, principal,
+ * and repayment are ASSETS, driven through typed morphisms by the loan lifecycle.
+ *
+ * Privacy boundary (see docs/design/zk-loan-app.md):
+ *   - PRIVATE (witness only): collateralValue, credit/income financials (income, score),
+ *     outstanding debt, and the blinding salts. Never on-chain, never in the event.
+ *   - PUBLIC (revealed): the loan principal amount, the collateral asset id (a locked
+ *     handle, not its private valuation), the lending-rule logicHash, loan status, and
+ *     the boolean "eligible" outcome — the chain learns *whether* the borrower qualifies,
+ *     never *why*.
+ *
+ * The ORIGINATION guard (`originate`, COLLATERAL_LOCKED -> ACTIVE) is the semi-private
+ * gate: it verifies an SP1-Groth16 eligibility proof over `witness.{publicValues,proof}`
+ * with the lender's pinned verifying key, AND binds the proof's committed public values
+ * (parsed out of the opaque `publicValues` blob with native JLVM `cat`/`substr`) to the
+ * PUBLIC lending rule — `exprHash == $lendingRuleLogicHash`, `outputHash == $keccakTrue`,
+ * and the `ok` bit — so a proof can only originate a loan if it proves THE pinned rule
+ * evaluated to `true` on the borrower's hidden data. A missing/garbage witness makes the
+ * guard false and the transition is gracefully rejected (state untouched).
+ *
+ * The pinned public constants ($lendingRuleVKey, $lendingRuleLogicHash, $keccakTrue) live
+ * on the loan's create-state so the guard is a closed expression. They are produced
+ * client-side by `src/apps/lending` helpers (`buildOriginationGuard`, `pinLendingRule`)
+ * over `src/zk` (`exprHash`, `KECCAK_TRUE`).
+ */
+export declare const lendingZkLoanDef: {
+    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 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 var: "state.lender";
+                    };
+                }];
+            }];
+        };
+        readonly dependencies: readonly [];
+    }];
+};