Skip to main content
This section summarizes all on-chain components that power the Aion-Fi protocol. Each contract plays a specific role in linking real payment flows from the PSP stack to deterministic execution on Soroban. Together, they create a verifiable system for advances, liquidity, yield distribution, identity validation, and FX anchoring.

​
What the system does

Aion-Fi turns real merchant receivables into a short-duration, self-liquidating on-chain asset. To make this possible, several smart contracts coordinate:

​
Core ideas

  • Liquidity Providers deposit USDC into a shared pool.
  • Merchants receive advances against receivables that settle at T+2.
  • The PSP sends settlement events, FX snapshots, and yield batches to the chain through a bridge.
  • Smart contracts verify, reconcile, and store these records.
  • Yield is distributed to LPs using Merkle proofs.
  • Identity is enforced through a non-transferable UID token.
  • Everything is auditable and tied to real receivable streams.

​
Components

ComponentPurpose
Bridge GatewayValidates signatures and routes off‑chain events to contracts.
Advance ContractRegisters merchant advances and reconciles repayments.
Liquidity PoolManages LP capital, shares, and redeployment cycles.
Yield DistributorAnchors yield batches and verifies Merkle proofs.
Participation TokenRepresents non-transferable LP participation.
KYC Identity RegistryHolds identity hashes and ensures UID gating.
FX OracleAnchors daily FX rates for deterministic accounting.

​
Bridge Gateway Contract

Central router that validates cryptographically signed off‑chain messages and dispatches them to the correct Soroban contract. 
pub struct BridgePayload {
    pub id: Bytes,
    pub action: Symbol,            // ADVANCE_REQUEST | SETTLEMENT_NOTICE | YIELD_ROOT_ANCHOR
    pub data_hash: Bytes,
    pub signature: Bytes,
}

pub trait BridgeGatewayContract {
    fn verify_payload(env: Env, payload: BridgePayload) -> Result<(), Error>;
    fn route_action(env: Env, payload: BridgePayload) -> Result<(), Error>;
}

​
Advance Contract

Registers and tracks merchant advances funded by LP liquidity, tied to FX snapshots and PSP settlement flow. 
pub struct Advance {
    pub id: Bytes,
    pub merchant_id: Bytes,
    pub amount_usdc: i128,
    pub fx_snapshot_id: Bytes,
    pub status: Symbol,        // REQUESTED | FUNDED | REPAID | FAILED
    pub created_at: u64,
}

pub trait AdvanceContract {
    fn register_advance(env: Env, data: Advance) -> Result<(), Error>;
    fn confirm_repayment(env: Env, advance_id: Bytes) -> Result<(), Error>;
    fn link_fx_snapshot(env: Env, advance_id: Bytes, fx_snapshot_id: Bytes) -> Result<(), Error>;
}

​
Liquidity Pool Contract

Tracks total liquidity, investor shares, and pool accounting. 
pub struct LiquidityPool {
    pub total_usdc: i128,
    pub total_shares: i128,
    pub participants: Map<Address, i128>,
}

pub trait LiquidityPoolContract {
    fn deposit(env: Env, investor: Address, amount: i128) -> Result<(), Error>;
    fn withdraw(env: Env, investor: Address, amount: i128) -> Result<(), Error>;
    fn set_participation(env: Env, investor: Address, shares: i128) -> Result<(), Error>;
    fn participation_of(env: Env, investor: Address) -> i128;
}

​
Yield Distributor Contract

Anchors Merkle roots for yield batches and verifies proofs. 
pub struct YieldRoot {
    pub id: Bytes,
    pub advance_id: Bytes,
    pub merkle_root: Bytes,
    pub total_yield: i128,
}

pub trait YieldDistributorContract {
    fn anchor_root(env: Env, root: YieldRoot) -> Result<(), Error>;
    fn verify_inclusion(env: Env, investor: Address, amount: i128, proof: Bytes, root_id: Bytes) -> bool;
}

​
Participation Token Contract

Non-transferable token (SBT-style) representing LP participation in the pool. 
pub struct ParticipationToken {
    pub investor: Address,
    pub shares: i128,
    pub issued_at: u64,
    pub active: bool,
}

pub trait ParticipationTokenContract {
    fn mint(env: Env, investor: Address, shares: i128) -> Result<(), Error>;
    fn burn(env: Env, investor: Address) -> Result<(), Error>;
    fn is_transferable(env: Env) -> bool;
}

​
NFT Registry Contract (KYC Identity)

Holds identity hashes and wallet bindings for UID enforcement. 
pub struct KYCIdentity {
    pub kyc_hash: Bytes,
    pub owner_wallet: Address,
    pub issued_at: u64,
    pub active: bool,
}

pub trait NFTRegistryContract {
    fn mint_identity(env: Env, identity: KYCIdentity) -> Result<(), Error>;
    fn rebind_wallet(env: Env, kyc_hash: Bytes, new_owner: Address) -> Result<(), Error>;
    fn revoke_identity(env: Env, kyc_hash: Bytes) -> Result<(), Error>;
}

​
FX Price Oracle Contract

Anchors daily FX snapshots used by the Advance and Yield systems. 
pub struct FXRate {
    pub pair: Symbol,
    pub buy_price: i128,
    pub sell_price: i128,
    pub timestamp: u64,
    pub proof: Bytes,
}

pub trait FXPriceOracleContract {
    fn update_rate(env: Env, rate: FXRate) -> Result<(), Error>;
    fn get_rate(env: Env, pair: Symbol) -> FXRate;
}