System Architecture

Introduction

This document provides a high-level overview of the Satoshi Lending Protocol’s architecture. For terminology and general workflow definitions, please refer to the Workflow Document.

Core Infrastructure

Oracle and Price Feeds

We utilize the Pyth Oracle to obtain real-time price information for collateral assets. Accurate price data is critical for the following operations:

• Borrowing
• Withdrawing collateral
• Liquidation

Note: User operations (and bots during liquidation) accept optional price data to update collateral prices before execution. Providing this data is highly recommended to prevent transaction failures due to stale prices.

Intents Contract

• Purpose: Exclusively handles asset swaps during the liquidation process.
• Interaction: The frontend should not interact with the Intents contract directly.

Frontend Workflows

This section details the interaction flows between the user/frontend and the smart contracts.

General Requirements

• Security Deposit: Most state-changing methods require attaching 1 yoctoNEAR as a security deposit.
• Storage Balance: Before interacting, ensure the user has a sufficient storage_balance registered on the relevant contract (Satoshi contract or Fungible Token contract).

1. Deposit (Lending & Collateral)

Deposits of USDC (lending) and non-USDC assets (collateral) are initiated directly via the Fungible Token (FT) contract.

Workflow:

1. Check Storage: Verify the user has a valid storage_balance on the Satoshi contract. If not, prompt the user to call storage_deposit.
2. Verify Registration: Confirm the user is registered.
3. External Deposit: User issues a deposit transaction on the deposit address of the external (non-Near) blockchain.
4. Poll Transaction: The system polls the external transaction until it is confirmed successful. This is a two-step process: you have to poll that the external transaction succeeds, and poll that the bridging action occurs on the Near side. However, OmniBridge may provide a single endpoint to query for both.
5. Contract Deposit: Once the external transaction is confirmed, the user initiates the deposit to the Satoshi contract.
6. Update UI: Poll the transaction about it’s status and if was success/failure.

2. Unlending (Withdraw USDC)

Lenders can withdraw their USDC principal and accrued interest directly to their Near account.

Workflow:

1. Check Storage: Verify the user has a valid storage_balance on the USDC Fungible Token contract. Register if necessary.
2. Execute Withdraw: Invoke the withdrawal method on the Satoshi contract (attach 1 yocto).
3. Handle Result: Parse the transaction result (success or failure, e.g., insufficient liquidity) and display it to the user.

3. Borrow USDC / Withdraw Collateral

Borrowers can withdraw borrowed USDC or their deposited collateral.

Key Considerations:

• Price Freshness: It is mandatory to submit off-chain hex-encoded Pyth price feed data with the transaction. Failure to do so can cause the transaction to fail.
• Price Update: All price feeds for all collateral assets must be updated during this transaction.

Workflow:

1. Check Storage: Verify the user has a valid storage_balance on the destination Fungible Token contract. Register if necessary.
2. Execute Transaction: Invoke the borrow or withdraw collateral method on the Satoshi contract (attach 1 yocto).
3. Handle Result: Parse the transaction result and display it to the user.

4. Repay Loan

Borrowers can repay borrowed USDC plus accrued interest.

Key Considerations:

• Overpayment Strategy: The frontend should perform a slight overpayment. Since interest compounds continuously and the exact transaction timestamp is unknown, this ensures the entire debt is covered.
• Excess Refund: Any excess USDC provided beyond the actual debt amount is automatically returned to the borrower.

Workflow:

1. Execute Repay: Invoke the repayment method on the Satoshi contract (attach 1 yocto).
2. Handle Result: Parse the transaction result and display it to the user.

Off-Chain Services

Bot

The bot handles automated maintenance tasks for the protocol. Responsibilities:

• Monitoring: Track Near token balance of Liquidation bot and raise alerts if they fall below a defined threshold.
• Simulation & Marking: Perform off-chain simulations to identify and “mark” unhealthy positions. This involves calculating:
  • Total Borrow Value: Adjusted for continuously accruing interest.
  • Total Collateral Value: Based on the latest real-time Pyth price information.
• Liquidation: Execute liquidation on marked users, including passing the necessary off-chain Pyth price data.

Querier

Status: Pending input. (Responsibilities to be defined)

Indexer

Status: Pending input. (Responsibilities to be defined)

Indexer REST API

Status: Pending input. (Responsibilities to be defined)