State Schema

GHOST stores all protocol state in MongoDB via Mongoose models. This page documents each model's fields, types, and relationships.

DepositSlot

Tracks a lender's deposit from initialization through confirmation or expiry.

Field	Type	Description
slotId	string	Unique identifier
userId	string	Lender's Ethereum address (lowercased)
token	string	Token address being deposited
amount	string	Deposit amount (BigInt as string)
status	string	pending, confirmed, or cancelled
encryptedRate	string	ECIES encrypted rate (set on confirm)
intentId	string	Associated lend intent ID (set on confirm)
epochId	string	Epoch in which the slot was created
createdAt	Date	Creation timestamp

Slots expire after 10 minutes if not confirmed. The expireOldSlots function runs periodically to clean these up.

LendIntent

Represents a confirmed lending position with an encrypted rate bid.

Field	Type	Description
intentId	string	Unique identifier
userId	string	Lender's Ethereum address (lowercased)
token	string	Token address
amount	string	Lending amount (BigInt as string)
encryptedRate	string	ECIES encrypted rate (hex string)
epochId	string	Associated epoch

Lend intents are consumed when they are included in an accepted match proposal. A single intent can be partially consumed across multiple proposals.

BorrowIntent

Represents a borrower's request for funds with collateral.

Field	Type	Description
intentId	string	Unique identifier
borrower	string	Borrower's Ethereum address (lowercased)
token	string	Token to borrow
amount	string	Borrow amount (BigInt as string)
encryptedMaxRate	string	Maximum acceptable rate (encrypted)
collateralToken	string	Collateral token address
collateralAmount	string	Collateral offered (BigInt as string)
status	string	pending, proposed, matched, cancelled, or rejected

Status transitions: pending -> proposed (when CRE generates proposal) -> matched (when proposal accepted) or rejected (when proposal rejected) or cancelled (user cancellation).

MatchProposal

A match generated by the CRE matching engine.

Field	Type	Description
proposalId	string	Unique identifier
borrowIntentId	string	Reference to the borrow intent
borrower	string	Borrower's address
token	string	Lending token
principal	string	Total matched amount (BigInt as string)
matchedTicks	array	Array of MatchedTick objects
effectiveBorrowerRate	number	Weighted average rate
collateralToken	string	Collateral token
collateralAmount	string	Total collateral
status	string	pending, accepted, rejected, or expired
expiresAt	Date	Deadline for borrower response

MatchedTick

Each matched tick within a proposal:

Field	Type	Description
lender	string	Lender's address
lendIntentId	string	Reference to the lend intent
amount	string	Amount filled from this tick (BigInt as string)
rate	number	The decrypted rate for this tick

Loan

An active, repaid, or defaulted loan.

Field	Type	Description
loanId	string	Unique identifier
borrower	string	Borrower's address
token	string	Lending token
principal	string	Total loan amount (BigInt as string)
matchedTicks	array	Array of MatchedTick objects
effectiveBorrowerRate	number	Blended rate
collateralToken	string	Collateral token
collateralAmount	string	Total collateral posted
requiredCollateral	string	Minimum required collateral at creation
maturity	Date	Loan maturity date
status	string	active, repaid, or defaulted
repaidAmount	string	Amount repaid (BigInt as string)

PendingTransfer

A queued fund movement waiting for CRE execution.

Field	Type	Description
id	string	Unique identifier
recipient	string	Destination address
token	string	Token to transfer
amount	string	Transfer amount (BigInt as string)
reason	string	Transfer reason (see Transfer Reasons)
createdAt	Date	When the transfer was queued
status	string	pending or completed

Balance

Internal balance tracking for each user and token pair.

Field	Type	Description
address	string	User's Ethereum address (lowercased)
token	string	Token address
amount	string	Current balance (BigInt as string)

Balances are modified via creditBalance and debitBalance helper functions that perform atomic updates.

CreditScore

Endogenous credit scoring for each user.

Field	Type	Description
address	string	User's Ethereum address (lowercased)
tier	string	bronze, silver, gold, or platinum
loansRepaid	number	Count of successfully repaid loans
loansDefaulted	number	Count of defaulted loans

New users are initialized at { tier: "bronze", loansRepaid: 0, loansDefaulted: 0 }.

State Helpers

The state.ts module exports helper functions for common state operations:

Function	Description
queueTransfer(params)	Create a pending transfer record
creditBalance(address, token, amount)	Increase a user's balance
debitBalance(address, token, amount)	Decrease a user's balance
getBalance(address, token)	Fetch current balance
getCreditScore(address)	Fetch or initialize credit score
upgradeTier(address)	Move credit tier up one level
downgradeTier(address)	Move credit tier down one level
getCollateralMultiplier(tier)	Return the multiplier for a tier
expireOldSlots()	Clean up deposit slots older than 10 minutes