Credit Market & Loan Engine

The Shamwari Credit Market & Loan Engine (nxt.ms.Loan, nxt.ms.CurrencyLending, nxt.ms.LoanRepayment, nxt.ms.LoanRescue) provides a protocol-native, decentralized peer-to-peer lending infrastructure built directly into the Shamwari core runtime.

Unlike smart-contract-based lending protocols that demand heavy over-collateralization and incur VM gas execution costs, Shamwari delivers structured credit markets with multi-lender crowdfunding, totem asset collateralization, quantitative risk scoring across eight credit tiers, lender portfolio diversification guardrails, and automated lifecycle management—including crowd-funded disbursements, partial payment tracking, and emergency third-party loan rescue.

---

Core Capabilities & Architecture

• Protocol-Native Credit Execution: Executed directly inside nxt.ms, bypassing virtual machine smart contracts to eliminate reentrancy vulnerabilities, gas dependencies, and execution overhead.
• Multi-Lender Crowdfunding: Loan applications function as time-boxed crowdfunding campaigns (LoanFundManager), enabling multiple lenders to pool capital into a single loan.
• Totem Asset Collateralization: Borrowers can lock native asset units (totemId, totemQNT) as loan collateral, which is automatically returned upon full repayment or transferred to a rescuer in a default event.
• Automated Lifecycle Processing: Block-height listeners (AFTER_BLOCK_APPLY) handle automated loan activations, overdue partial distributions, and collateral/fund refunds for expired applications.
• Distressed Loan Rescue: Emergency recovery mechanism (nxt.ms.LoanRescue) allowing third-party accounts to repay outstanding debt on defaulted loans in exchange for taking ownership of the locked collateral.
• Lender Portfolio Protections: Enforces single-loan caps, per-currency limits, and risk-tier concentration bounds via CurrencyLending.LenderProtection.
• Integrated Fiscal Tax Collection: Protocol-level tax deductions are calculated via TaxCalculator and credited to the designated BetaChain tax collector on both lending and repayment settlement events.

---

Loan Status & Lifecycle State Machine

A loan transitions through six distinct operational states managed by nxt.ms.Loan.LoanStatus:

Status	Description	Condition & Trigger
PENDING	Pending Funding	Loan application active; funding deadline (issuance_height) is in the future and total required amount is not yet raised.
FUNDED	Active Loan	Loan fully funded (raisedAmountQNT >= amountQNT); principal disbursed to borrower; awaiting repayment prior to repayment_height.
REPAID	Paid in Full	Borrower has settled total due amount (repaidAmountQNT >= totalDueAmountQNT); collateral released to borrower.
OVERDUE	Overdue	Repayment deadline passed (repayment_height <= currentHeight); loan remains unpaid and unrescued.
RESCUED	Rescued by Third Party	Defaulted loan paid off by a third-party rescuer; borrower collateral transferred to the rescuer.
FAILED	Failed to Raise Funds	Funding deadline passed (issuance_height <= currentHeight) without raising target amount. All contributions refunded to lenders and collateral unlocked.

                       ┌───────────────────────────────┐
                       │   Loan Application Submitted  │
                       └───────────────┬───────────────┘
                                       │
                                       ▼
                         ┌───────────────────────────┐
                         │      PENDING FUNDING      │
                         └─────┬───────────────┬─────┘
                               │               │
      Target Amount Raised     │               │  Funding Deadline Reached
    (raisedAmount >= amount)   │               │  (height >= issuance_height)
                               ▼               ▼
                         ┌───────────┐   ┌───────────┐
                         │  FUNDED   │   │  FAILED   │
                         └─────┬─────┘   └───────────┘
                               │               ▲
          Repayment Deadline   │               │  (Collateral & Contributions
          Reached Unpaid       │               │   Refunded to Parties)
                               ▼               │
                         ┌───────────┐         │
                         │  OVERDUE  │─────────┘
                         └─────┬─────┘
                               │
            ┌──────────────────┴──────────────────┐
            │                                     │
            ▼                                     ▼
     ┌─────────────┐                       ┌─────────────┐
     │   REPAID    │                       │   RESCUED   │
     └─────────────┘                       └─────────────┘
  (Paid by Borrower)                    (Paid by Rescuer)

---

Data Model & Relational Schema

The Credit System maintains relational database tables indexed by transaction hashes, loan IDs, block height, and account keys.

1. Primary Credit Entities

Table	Primary / Composite Key	Entity Class	Description
public.loan	id, height	Loan	Core loan application, parameters, state flags, and borrower details.
public.loan_fund_manager	id, height	LoanFundManager	Versioned tracking table for aggregate crowdfunding contributions raised ($QNT$).
public.loan_manager	id, height	LoanManager	Versioned tracking table for cumulative repayments made ($QNT$).
public.currency_lending	full_hash, id	CurrencyLending	Individual lender contribution records, linking loan IDs to lender accounts.
public.loan_repayment	full_hash, id	LoanRepayment	Borrower repayment transaction logs with associated tax deductions.
public.loan_rescue	full_hash, id	LoanRescue	Distressed loan recovery logs tracking third-party rescuer settlements.

2. Primary Loan Record (public.loan)

Field	Type	Description
id	long	Transaction ID of initial loan application (globally unique handle).
account_id	long	Borrower account ID.
chain	int	BetaChain identifier hosting the loan transaction context.
totem_id	long	Identifier of the locked totem collateral asset.
totem_qnt	long	Quantity of totem units held as collateral ($QNT$).
currency_id	long	Target currency handle requested for the loan principal.
amount	long	Requested principal amount in atomic currency units ($QNT$).
interest_rate	long	Total loan interest rate expressed in basis points ($0 \text{ to } 10,000$, where $100 \text{ bps} = 1\%$).
issuance_height	int	Funding deadline block height. Must be fully funded by this block.
repayment_height	int	Repayment maturity block height. Total due must be repaid by this block.
funded	boolean	Flag set to true when aggregate contributions meet or exceed principal.
repaid	boolean	Flag set to true when cumulative repayments cover principal and interest.
rescued	boolean	Flag set to true if a third party covered the outstanding debt.
rescuer_id	long	Account ID of the third-party rescuer (if rescued == true).
creation_height	int	Block height at which the loan application was submitted.

---

Mathematical Formulas & Calculations

1. Total Interest & Amount Due Calculation

Interest is specified in basis points ($1 \text{ bps} = 0.01\%$). Interest is calculated using 8-decimal precision rounding:

$\text{InterestQNT} = \left\lfloor \text{amountQNT} \times \frac{\text{interestRate}}{10000} \right\rfloor$

$\text{TotalDueAmountQNT} = \text{amountQNT} + \text{InterestQNT}$

2. Lender Interest Share Attribution

When a loan is repaid, each lender receives their initial principal contribution plus a pro-rata share of the collected interest based on their share of total principal contributed:

$\text{LenderInterestShareQNT} = \left\lfloor \text{InterestQNT} \times \frac{\text{lenderUnitsQNT}}{\text{amountQNT}} \right\rfloor$

$\text{TotalLenderReturnQNT} = \text{lenderUnitsQNT} + \text{LenderInterestShareQNT}$

3. Partial Repayment Share Calculation

During partial repayments or overdue partial distributions, funds are disbursed proportionally across all contributing lenders:

$\text{LenderProRataShareQNT} = \left\lfloor \text{totalRepaidQNT} \times \frac{\text{lenderUnitsQNT}}{\text{amountQNT}} \right\rfloor$

4. Remaining Owed Amount & Funding Progress

$\text{OwedAmountQNT} = \text{TotalDueAmountQNT} - \text{repaidAmountQNT}$

$\text{FundingProgress (\%)} = \left( \frac{\text{raisedAmountQNT}}{\text{amountQNT}} \right) \times 100$

$\text{RemainingDays} = \max \left( 0, \frac{\text{repaymentHeight} - \text{currentHeight}}{7200} \right)$

---

Detailed Lifecycle Operations

1. Application Validation Rules

When nxt.ms.Loan.addLoanApplication() is invoked, the engine enforces compliance checks prior to publishing:

1. Positive Principal: $\text{amountQNT} > 0$ and $\text{amountQNT} \le 1,000,000,000,000$. Unsecured loans cannot exceed $1,000,000,000 \text{ QNT}$.
2. Interest Bounds: $100 \le \text{interestRate} \le 5000 \text{ bps}$ ($1\% \text{ to } 50\%$).
3. Height Hierarchy: $\text{currentHeight} < \text{issuanceHeight} < \text{repaymentHeight}$.
4. Fundraising Period: $1,440 \le (\text{issuanceHeight} - \text{currentHeight}) \le 43,200 \text{ blocks}$ ($1 \text{ to } 30 \text{ days}$).
5. Duration Bounds: $1,440 \le (\text{repaymentHeight} - \text{issuanceHeight}) \le 432,000 \text{ blocks}$ ($1 \text{ to } 300 \text{ days}$).
6. Collateral Availability: Borrower must hold sufficient unencumbered totem balance: $\text{totemBalanceQNT} \ge \text{totemQNT}$. Collateral is locked immediately upon creation.
7. Active Loan Ceiling: A borrower account cannot exceed $\text{MAX\_ACTIVE\_LOANS\_PER\_ACCOUNT} = 5$.

2. Multi-Lender Contributions (CurrencyLending)

Lenders contribute currency units to pending loans via LendingAttachment.

• Minimum Contribution: $\text{MIN\_LENDING\_AMOUNT} = 1,000,000 \text{ QNT}$.
• Automatic Activation: As contributions accumulate in LoanFundManager, once $\text{raisedAmountQNT} \ge \text{amountQNT}$, fundAmountQNT() triggers loan activation:
  1. Principal units are transferred from each lender to the borrower (less tax).
  2. The borrower's AccountCurrencyLoanUnits is registered with target maturity height repaymentHeight.
  3. Tax is credited via CurrencyTaxRecord.creditTaxAccount().
  4. Emits Loan.Event.LOAN.

3. Settlement & Repayment Flow (LoanRepayment)

Borrowers submit repayments using LoanRepaymentAttachment.

• Cumulative Tracking: Increments repaidAmountQNT in LoanManager.
• Full Repayment Trigger: When $\text{repaidAmountQNT} \ge \text{TotalDueAmountQNT}$, completeRepayment() executes:
  1. Computes total returns ($\text{principal} + \text{pro-rata interest}$) for each lender in currency_lending.
  2. Calculates protocol settlement tax using TaxCalculator.computeTotalTax().
  3. Credits net funds plus tax adjustment to lender accounts.
  4. Unlocks and returns $100\%$ of locked totem collateral (totemQNT) to the borrower's unconfirmed totem balance.
  5. Emits Loan.Event.LOAN_REPAYMENT.

4. Overdue Handling & Third-Party Rescue (LoanRescue)

If repaymentHeight is reached without full repayment:

• Overdue Processing: processOverdueLoan() distributes any available partial repayments pro-rata to lenders based on their contribution share.
• Third-Party Rescue Execution: Any third-party account can invoke rescueLoan():

  // Third-party rescuer pays remaining debt and assumes collateral
  loan.rescueLoan(event, eventId, transaction);

  1. Rescuer pays remaining owed units ($\text{TotalDueAmountQNT} - \text{repaidAmountQNT}$) distributed directly to lenders.
  2. Prior partial repayments made by the borrower are credited back to the borrower's unconfirmed balance.
  3. $100\%$ of borrower's locked collateral (totemQNT) is transferred directly to the rescuer account.
  4. Sets rescued = true, repaid = true, and assigns rescuerId. Emits Loan.Event.LOAN_RESCUE.
  5. Safety Caps: Rescuers are limited to a maximum of $10$ rescued loans per account and $\text{MAX\_RESCUE\_EXPOSURE} = 50,000,000,000 \text{ QNT}$.

5. Expiration of Unfunded Loans

If issuanceHeight is reached and $\text{raisedAmountQNT} < \text{amountQNT}$:

• Block listener executes processFailedLoanApplication():
  1. $100\%$ of locked totem collateral is returned to the borrower.
  2. Aggregate contributions are refunded to each respective lender's unconfirmed currency balance.
  3. Loan status updates to FAILED and record is purged from active tables. Emits Loan.Event.LOAN_FAILED.

---

Risk Management & Credit Scoring Model

Shamwari implements a quantitative credit evaluation model through RiskCalculator, scoring loan applications across key risk vectors to classify borrowers into standardized credit tiers.

1. Credit Tier Framework & Risk Premiums

Credit Tier	Classification & Risk Profile	Quality Score Ceiling	Risk Premium (Basis Points)
AAA	Excellent — Low Risk	Baseline	$50 \text{ bps } (0.5\%)$
AA	Very Good — Low Risk	High Quality	$100 \text{ bps } (1.0\%)$
A	Good — Moderate Risk	Standard Quality	$200 \text{ bps } (2.0\%)$
BBB	Average — Moderate Risk	Acceptable	$350 \text{ bps } (3.5\%)$
BB	Below Average — High Risk	$\ge 0.50$	$500 \text{ bps } (5.0\%)$
B	Poor — High Risk	$\ge 0.40$	$750 \text{ bps } (7.5\%)$
C	Very Poor — Very High Risk	$\ge 0.30$	$1,000 \text{ bps } (10.0\%)$
D	Default — Extreme Risk	$< 0.30$	$1,500 \text{ bps } (15.0\%)$

2. Multi-Factor Risk Assessment Weights

$S_{\text{risk}} = 0.35 \cdot W_{\text{collateral}} + 0.25 \cdot W_{\text{history}} + 0.20 \cdot W_{\text{LTV}} + 0.15 \cdot W_{\text{duration}} + 0.05 \cdot W_{\text{currency}}$

• Collateral Quality ($35\%$): Asset stability, liquidity, and age of totem collateral.
• Borrower History ($25\%$): On-chain track record of past repaid loans vs. defaults.
• Loan-to-Value (LTV) Ratio ($20\%$): Ratio of principal requested to total collateral valuation.
• Loan Duration ($15\%$): Exposure time window in block height.
• Currency Volatility ($5\%$): Price stability of the borrowed currency token.

3. Lender Portfolio Diversification Guardrails (LenderProtection)

To prevent catastrophic lender concentration, CurrencyLending.LenderProtection enforces protocol-level checks prior to accepting lending transactions:

Constraint Type	Limit Parameter	Purpose
Single Loan Exposure	$\le 10\%$ of Portfolio	Prevents over-exposure to any single borrower or loan application.
Currency Concentration	$\le 30\%$ of Portfolio	Mandates multi-currency diversification across active loan assets.
Risk-Tier Ceiling	$\le 40\%$ of Portfolio	Limits capital allocation in high-risk tiers (BB through D).
Borrower Exposure Cap	$10,000,000,000 \text{ QNT}$	Maximum aggregate loan exposure allowed to a single borrower account.
Total Lending Cap	$100,000,000,000 \text{ QNT}$	Maximum active aggregate lending exposure per lender account.

---

Governance & Operational Parameters

Parameters governing credit markets on Shamwari Network as defined in nxt.ms.LoanConstants:

Parameter	Value	Standard Units	Operational Scope
MIN_LOAN_FUNDRAISING_PERIOD	$1,440 \text{ blocks}$	$\sim 1 \text{ Day}$	Minimum crowdfunding window.
MAX_LOAN_FUNDRAISING_PERIOD	$43,200 \text{ blocks}$	$\sim 30 \text{ Days}$	Maximum crowdfunding window.
MIN_LOAN_DURATION	$1,440 \text{ blocks}$	$\sim 1 \text{ Day}$	Minimum loan maturity term.
MAX_LOAN_DURATION	$432,000 \text{ blocks}$	$\sim 300 \text{ Days}$	Maximum loan maturity term.
MIN_LOAN_INTEREST_RATE	$100 \text{ bps}$	$1.0\%$	Minimum allowable interest rate.
MAX_LOAN_INTEREST_RATE	$5,000 \text{ bps}$	$50.0\%$	Consumer protection interest ceiling.
MAX_LOAN_AMOUNT	$1,000,000,000,000 \text{ QNT}$	$10,000 \text{ Units}$	Maximum total loan principal.
MAX_UNSECURED_LOAN_AMOUNT	$1,000,000,000 \text{ QNT}$	$10 \text{ Units}$	Ceiling for loans without totem collateral.
MAX_ACTIVE_LOANS_PER_ACCOUNT	$5$	Active Loans	Borrower concurrency limit.
MAX_RESCUED_LOANS_PER_ACCOUNT	$10$	Rescued Loans	Maximum defaulted loans a single account may rescue.
MAX_RESCUE_EXPOSURE	$50,000,000,000 \text{ QNT}$	$500 \text{ Units}$	Maximum aggregate rescue capital per rescuer.
LOAN_APPLICATION_COOLDOWN	$1,440 \text{ blocks}$	$\sim 1 \text{ Day}$	Cooldown between subsequent application submissions.

---

Event Listener Matrix

The Credit Engine exposes strongly-typed listeners across entity classes to support real-time block indexers and off-chain analytics engines:

Entity Class	Event Enum	Trigger Condition
Loan	Event.LOAN_APPLICATION	New loan application validated and added to order book.
Loan	Event.LOAN	Loan crowdfunding target reached; funds disbursed to borrower.
Loan	Event.LOAN_REPAYMENT	Borrower completes full repayment; collateral unlocked.
Loan	Event.LOAN_RESCUE	Third party executes rescue payment and claims collateral.
Loan	Event.LOAN_FAILED	Fundraising deadline expired without full funding; refunds issued.
CurrencyLending	Event.LENDING	Lender contribution successfully processed into crowdfunding pool.
LoanRepayment	Event.LOAN_REPAYMENT	Individual partial or full repayment transaction recorded.
LoanRescue	Event.LOAN_RESCUE	Distressed loan rescue transaction recorded.

---

Related APIs

API	Description
GetLoan	Get loan by ID
GetLoanApplications	List loan applications
GetActiveLoans	List active loans
GetOverdueLoans	List overdue loans
GetPaidLoans	List paid loans
GetAccountCurrencyLoans	Get account currency loans
Loans API	All loan operations

Primary Use Cases

• Collateralized Micro-Lending: Retail and business borrowers leverage native totem assets as collateral to secure liquidity in fiat-backed sovereign currencies (ZWG, ZAR, BRL).
• Institutional Debt Crowdfunding: Syndicated funding pools where multiple institutional lenders co-fund high-value business loans with automated pro-rata interest distribution.
• Distressed Debt Liquidation: Specialized arbitrageurs and recovery funds step in via nxt.ms.LoanRescue to make lenders whole while acquiring collateral assets at discount valuations.