DEV Community: Nacho Colomina Torregrosa

How Equillar Uses On-Chain Collateral to Protect Investors

Nacho Colomina Torregrosa — Fri, 06 Mar 2026 17:46:03 +0000

Introduction

One of the questions I kept coming back to during the development and improvement of the Equillar contract is: what happens if the project fails or doesn't generate the expected income? Investors need some kind of guarantee — and even better if it's verifiable, trustless, and enforced by code. What I ended up building is an on-chain collateral mechanism that projects can use to back their payment obligations. This article explains how it works under the hood.

The problem: a promise without a guarantee isn't enough

The Equillar contract lets projects raise funding from investors in exchange for periodic payments that include principal plus interest. A model similar to a bond, but entirely on-chain on the Stellar network.

The obvious risk is default: if the company doesn't transfer funds to the contract on time, investors don't get paid. In traditional finance this is managed with bank guarantees or credit insurance; in blockchain we have something more direct: assets locked inside the contract itself that act as collateral.

Collateral as an on-chain guarantee

The idea is simple: the address registered by the company at deployment time transfers collateral tokens to the contract. Those tokens are locked there and can be liquidated to pay investors if the project can't meet its obligations.

The contract stores the collateral state in a Collateral struct:

pub struct Collateral {
    pub token_collateral_address: Address,      // which token is used as collateral
    pub token_collateral_symbol: String,        // human-readable symbol (e.g. "USDC" ....)
    pub address_collateral_token: Address,      // who deposited the collateral
    pub collateral_amount: i128,                // total amount deposited
    pub collateral_level: u32,                  // coverage in basis points
}

The contract also keeps internal accounting related to collateral in its balance:

pub collateral_received: i128,     // total collateral received so far
pub collateral_liquidated: i128,   // total already used to pay investors
pub payment_obligations: i128,     // sum of what the contract owes all investors

This makes it possible to know at any time how much real backing exists versus how much is owed.

How the contract manages collateral deposits

The public function that accepts collateral deposits has this signature:

pub fn add_collateral(
    env: Env,
    collateral_token_addr: Address,
    collateral_token_amount: i128,
    collateral_token_symbol: String,
    collateral_addr: Address,
) -> Result<Collateral, Error>

Reflector is used as the price oracle, and its address is fixed in the constructor and stored in ContractData.

// In the constructor — set once by the admin:
ContractData { ..., price_oracle, ... }

// In add_collateral — read from storage, not accepted as a parameter:
let contract_data = Storage::get_contract_data(&env);
// → contract_data.price_oracle

Execution follows these ordered steps:

Authentication

collateral_addr.require_auth();

The contract requires the transaction to be signed by the address that will deposit the collateral. No one can deposit collateral on behalf of another without their explicit signature.

Single token rule

if let Some(coll) = Storage::get_collateral(&env) {
    if coll.token_collateral_address != collateral_token_addr {
        return Err(Error::OnlyOneCollateralTokenAllowed);
    }
}

If collateral is already registered and the token being deposited differs from the existing one, the contract rejects the operation. This greatly simplifies valuation and prevents the collateral from being fragmented across multiple assets with independent prices.

Balance check

if collateral_token_client.balance(&collateral_addr) < collateral_token_amount {
    return Err(Error::AddressInsufficientBalance);
}

A preventive check before attempting the transfer. It's cleaner to return a descriptive error than to let the token reject it with a generic one.

Actual transfer to the contract

collateral_token_client
    .try_transfer(&collateral_addr, &env.current_contract_address(), &collateral_token_amount)
    .map_err(|_| Error::RecipientCannotReceivePayment)?
    .map_err(|_| Error::InvalidPaymentData)?;

Tokens are transferred from the depositor to the contract's own address. From this point on, the contract is the real custodian of those assets.

Internal balance update

let mut contract_balances = Storage::get_balances_or_new(&env);
contract_balances.recalculate_from_collateral_received(&collateral_token_amount);
Storage::update_contract_balances(&env, &contract_balances);

The collateral_received counter is incremented, keeping an accounting record of how much has been accumulated.

The coverage level: measuring the guarantee with a price oracle

Depositing tokens into the contract is necessary but not sufficient. What really matters for investors is whether the value of the collateral covers the pending obligations. To calculate this, the contract needs to query an external oracle, as mentioned above, we use Reflector.

How the oracle interface is defined

In Soroban, to call an external contract we can declare its interface as a Rust trait and annotate it with #[contractclient]. The SDK automatically generates a typed client from that declaration.

For Reflector we need two data types upfront: the Asset enum, which represents how to identify a token in the oracle, and PriceData, which is what it returns when asked for a price:

#[contracttype]
pub enum Asset {
    Stellar(Address),   // token deployed on Stellar (SAC or contract)
    Other(Symbol),      // native asset like XLM
}

#[contracttype]
pub struct PriceData {
    pub price: i128,      // price in units of the quote asset
    pub timestamp: u64,   // timestamp of the last recorded tick
}

With those types defined, the trait declares the two oracle functions we care about:

#[contractclient(name = "ReflectorClient")]
pub trait ReflectorOracle {
    fn decimals(env: &Env) -> u32;
    fn x_last_price(env: &Env, base_asset: Asset, quote_asset: Asset) -> Option<PriceData>;
}

The #[contractclient(name = "ReflectorClient")] macro does the heavy lifting: it generates a ReflectorClient struct with methods for each function in the trait. At runtime, each call to those methods becomes a cross-contract invocation to the address passed in. The compiler guarantees that the types match, and the Soroban runtime guarantees that the call is atomic with the rest of the transaction.

Calling the oracle is then as straightforward as:

let oracle = ReflectorClient::new(env, &contract_data.price_oracle);
let oracle_decimals = oracle.decimals();
let price_data = oracle.x_last_price(
    &Asset::Stellar(collateral_token_addr.clone()),
    &Asset::Stellar(contract_token_addr.clone()),
)?; // None if the pair has no price → the deposit is rejected

The mock in tests

For unit tests we don't want to depend on a real oracle deployed on the network. Since the oracle is just a trait, we can implement it in a stub contract that returns a fixed price:

#[contract]
pub struct ReflectorMock;

#[contractimpl]
impl ReflectorOracle for ReflectorMock {
    fn x_last_price(_env: &Env, _base: Asset, _quote: Asset) -> Option<PriceData> {
        Some(PriceData { price: 936, timestamp: 65587445447 })
    }
    fn decimals(_env: &Env) -> u32 { 3 }
}

4.3 The coverage calculation

The valuation logic lives in calculate_collateral_level, whose signature is:

pub fn calculate_collateral_level(
    env: &Env,
    oracle_addr: &Address,
    collateral_token_addr: &Address,
    collateral_amount: i128,
    collateral_decimals: u32,
    contract_token_addr: &Address,
    contract_token_decimals: u32,
    payment_obligations: i128,
) -> Option<u32>

Let's walk through its logic step by step:

Step 1 — Check if there's anything to back. If there are no investors yet, payment_obligations is zero and computing any ratio is meaningless. The function returns None and the contract rejects the deposit:

if payment_obligations == 0 {
    return None;
}

Step 2 — Query the price from the oracle. The Reflector client is instantiated with the address stored in ContractData and two things are requested: the oracle's own decimals (needed to normalise the price) and the price of the collateral token expressed in the investment token. If the pair is not registered in Reflector, x_last_price returns None and the ? operator propagates that None outward:

let oracle = ReflectorClient::new(env, oracle_addr);
let oracle_decimals = oracle.decimals();

let price_data = oracle.x_last_price(
    &Asset::Stellar(collateral_token_addr.clone()),
    &Asset::Stellar(contract_token_addr.clone()),
)?;

Step 3 — Normalise to 18 decimals (OpenZeppelin Wad). price_data.price is an integer that carries the oracle's decimals embedded in it. The Wad library converts it to a fixed-point representation with 18 internal decimals:

let price_wad = Wad::from_token_amount(env, price_data.price, oracle_decimals as u8);

Step 4 — Collateral value in the investment currency. The collateral amount is normalised the same way and multiplied by the price. The result is then brought back (to_token_amount) to the decimals of the contract token:

let collateral_wad = Wad::from_token_amount(env, collateral_amount, collateral_decimals as u8);
let collateral_value_wad = collateral_wad * price_wad; // both normalised to 18 decimals
let collateral_value = collateral_value_wad.to_token_amount(env, contract_token_decimals as u8); // result expressed in the contract token's decimals

Step 5 — Coverage ratio in basis points. The collateral value is multiplied by 10_000_i128 and divided by the total obligations. The result is an integer with two implicit decimals: 6000 means 60.00% coverage; 10000 means 100%:

let level = collateral_value * 10_000_i128 / payment_obligations;
Some(level as u32)

This straightforward integer division is precise enough here because collateral_value is already expressed in the contract token's units after the previous step. Wad was necessary in steps 3 and 4 to normalise price and amount across tokens with different decimal counts.
The function returns None if the oracle has no price for the pair, causing add_collateral to treat that case the same as an insufficient coverage level and reject the deposit.

Tests

Having the logic split across well-defined functions and a trait-based oracle makes the whole mechanism straightforward to test without any external dependencies.

Success: depositing collateral and verifying the coverage level

With ~155 tokens invested and the mock oracle returning a price of 936 (3 decimals = 0.936), depositing 100 collateral tokens should yield exactly 60% coverage. A second deposit of another 100 tokens then pushes the level above 60%, since it accumulates on top of the first:

// ~155 tokens invested, 100 collateral tokens deposited
// Oracle (fixed in the constructor) returns price: 936 with 3 decimals
let collateral = test_data.client.add_collateral(
    &token_collateral.address,
    &100_i128,
    &String::from_str(&e, "TEST"),
    &collateral_addr,
);

assert_eq!(collateral.collateral_level, 6000_u32); // 60% coverage

// Depositing another 100 tokens raises the level (now 200 tokens vs ~155 obligations)
let collateral = test_data.client.add_collateral(
    &token_collateral.address,
    &100_i128,
    &String::from_str(&e, "TEST"),
    &collateral_addr,
);

assert!(collateral.collateral_level > 6000_u32); // now > 60%

Error cases

The contract can return three specific errors related to collateral. Each one protects something different:

Error (code)	When it occurs	What it protects
`AddressInsufficientBalance` (#1)	The depositor doesn't have enough tokens	Prevents a failed collateral transfer
`OnlyOneCollateralTokenAllowed` (#34)	A second token type is being deposited	Simplicity and comparability of collateral
`CollateralLevelTooLow` (#33)	The deposit doesn't reach a minimum coverage level	Prevents decorative collateral that covers nothing

// Error #1: no balance in the depositor's wallet
#[should_panic(expected = "HostError: Error(Contract, #1)")]
fn test_add_collateral_insufficient_balance() {
    // Token is created but NOT minted to collateral_addr
    test_data.client.add_collateral(
        &token_collateral.address, &100_i128, &String::from_str(&e,"TEST"), &collateral_addr
    );
}

// Error #34: two different tokens in the same contract
#[should_panic(expected = "HostError: Error(Contract, #34)")]
fn test_add_collateral_only_one_collateral_token_allowed() {
    // First deposit with token_collateral → OK
    test_data.client.add_collateral(&token_collateral.address, &100_i128, ...);

    // Second deposit with token_collateral_2 → rejected
    test_data.client.add_collateral(&token_collateral_2.address, &100_i128, ...);
}

Conclusion: programmable trust for investors and companies

What we've built isn't complicated conceptually, but it is in its implications. A project that deposits collateral into the contract is making a promise that the code will enforce — with or without their future cooperation. Investors can check the coverage level at any time with a simple on-chain query. No need to trust external audits or certificates: the blockchain itself is the record.

In the next articles we'll look at how to liquidate the collateral — that is, pay investors in proportion to the amount they deposited — and how to return the collateral to the company once all payment obligations have been fulfilled.

You can see and explore the code in the equillar contract github repo: https://github.com/icolomina/equillar-soroban (Branch equillar_collateral)

After finishing the rest of the functionalities (liquidate the collateral and return the collateral to the company) the branch will be merged to main.

Tokenizing Investments with NFTs on Equillar

Nacho Colomina Torregrosa — Sun, 15 Feb 2026 09:41:03 +0000

Introduction

A few days ago I faced an interesting problem: how to manage multiple investments per user in the Equillar contract? The traditional solution would be something like Map<Address, Vec<Investment>>, but then I wondered: what if each project was an NFT and each investment a minted token id?

Let me tell you how I implemented it using the OpenZeppelin's stellar-tokens.

The Original Problem

Imagine an investment contract where:

Users can invest multiple times
Each investment has independent monthly payments
Users should be able to sell/transfer their investments

With the traditional approach, transferring a specific investment would require complicated custom logic. With NFTs, it comes almost for free.

The Solution: NFTs as Investment Certificates

Every time a contract is deployed, the constructor:

Loads the project investment conditions (rate, goal, return months etc ...).
Stores the NFT metadata (token_uri, name and symbol).
Foreach investment a new token id is minted. This ID token relates the address that have invested with its corresponding data (earnings, payment start date, etc.)

Let's explore it step by step:

Basic Setup

First, we add the dependency:

[dependencies]
stellar-tokens = "0.6.0"

And make our contract implements the OpenZeppelin's NonFungibleToken trait:

use stellar_tokens::non_fungible::{Base, NonFungibleToken};

#[contractimpl(contracttrait)]
impl NonFungibleToken for InvestmentContract {
    type ContractType = Base;   
}

That's it. You now have working NFT.

Constructor: Initializing the Collection

In the constructor, you need to configure the NFT collection metadata:

pub fn __constructor(
        env: Env,
        owner_addr: Address,
        project_address: Address,
        token_addr: Address,
        uri: String,
        name: String,
        symbol: String,
        investment_params: InvestmentContractParams
    ) -> Result<(), Error> {
        owner_addr.require_auth();
        // validations ...
        InvestmentReturnType::from_number(investment_params.return_type).ok_or(Error::UnsupportedReturnType)?;

        ownable::set_owner(&env, &owner_addr);
        let contract_data = ContractData::from_investment_contract_params(&investment_params, token_addr, project_address);

        // Add NFT metadata
        Base::set_metadata(&env, uri, name, symbol);
        Storage::update_contract_data(&env, &contract_data);
        Ok(())
    }

What do these parameters do?

uri: Base URL for metadata (e.g., "https://project.com")
name: Collection name (e.g., "InvestmentNFT")
symbol: Short symbol (e.g., "INVST")

Minting: A new Token ID for each investment

Here's the magic. When someone invests, we mint a new token and link it to the investment data:

pub fn invest(env: Env, addr: Address, amount: i128) -> Result<Investment, Error> {
    addr.require_auth();

    // 1. Validations
    let contract_data = Storage::get_contract_data(&env);
    validation::validate_investment(amount, &contract_data, ...)?;

    // 2. Transfer tokens to contract
    let tk = get_token(&env, &contract_data);
    tk.transfer(&addr, &env.current_contract_address(), &amount)?;

    // 3. Mint the NFT (sequential: 0, 1, 2, ...)
    let token_id = Base::sequential_mint(&env, &addr);

    // 4. Create and store investment data using token_id as key
    let investment = Investment::new(&env, &contract_data, &amount, decimals, token_id);
    Storage::update_investment(&env, token_id, &investment);

    Ok(investment)
}

The important part:

Base::sequential_mint(&env, &addr) mints a new token to the investor's address and returns the token_id
We use that token_id as the key to store the investment data
The NFT and investment are linked forever

Storage: Two Connected Worlds

We have two independent but related storages:

NFT Storage (stellar-tokens):

NFTStorageKey::Owner(token_id) → Address  // Who owns the NFT

Investment Storage (ours):

DataKey::Investment(token_id) → Investment  // That investment's data

When transferring the NFT, only the first storage changes. The investment data stays there, but now "belongs" to the new NFT owner.

Claiming Payments

When a user wants to claim their payments, we use the NFT to verify ownership:

pub fn claim(env: Env, token_id: u32) -> Result<Investment, Error> {
    // 1. Verify caller owns the NFT
    let addr: Address = Self::owner_of(&env, token_id);
    addr.require_auth();

    // 2. Get investment data
    let mut investment = Storage::get_investment(&env, token_id)
        .ok_or(Error::AddressHasNotInvested)?;

    // 3. Process pending payments
    let amount = investment.process_payments(&env, &contract_data);

    // 4. Transfer tokens
    let tk = get_token(&env, &contract_data);
    tk.try_transfer(&env.current_contract_address(), &addr, &amount)?;

    // 5. Update state
    Storage::update_investment_with_claim(&env, token_id, &investment);

    Ok(investment)
}

Self::owner_of(&env, token_id) tells us who currently owns the NFT. If Alice sold her NFT #42 to Bob, owner_of(42) now returns Bob's address.

Free Secondary Market

This is the best part: any Stellar NFT-compatible marketplace can list these tokens. The flow would be:

Alice invests 1000 USDC → receives NFT #42
Alice lists NFT #42 on a marketplace for 1100 USDC
Bob buys the NFT
Bob can now claim the remaining monthly payments

You don't need extra code. When transferring the NFT, the payment rights go with it.

Methods You Get Automatically

By implementing NonFungibleToken, you get for free:

balance(account) — how many investment NFTs a user has
owner_of(token_id) — who is the current owner
transfer(from, to, token_id) — transfer the NFT
approve(approver, approved, token_id) — give permission to a third party (approved)
token_uri(token_id) — metadata URL

All work out-of-the-box. You can call them from other contracts or from a frontend.

Advantages of This Approach

Advantages:

✅ Native transferability of investments
✅ Compatibility with explorers and wallets
✅ Less custom code
✅ Multiple investments per user without complications
✅ Each investment is independent

Tradeoffs:

⚠️ You need to manage an additional token_id
⚠️ Minting has a cost (small, but exists)

Conclusion

Using NFTs to manage investments turned out to be more elegant than I expected. The code is simpler, transferability is native, and ecosystem integration comes for free.

Is it the right approach for everything? No, but it's useful because it allows easily assigning more than one investment per user in the same project and transferring them easily if the user wants to.

If you're building something similar, check out OpenZeppelin's stellar-tokens. The library does the heavy lifting for you.

Resources

Improving the Equillar Contract with OpenZeppelin

Nacho Colomina Torregrosa — Sat, 24 Jan 2026 18:02:12 +0000

Introduction

I'm constantly researching ways to improve the code for the Equillar contract, and I recently discovered the OpenZeppelin libraries for Stellar.

While exploring them, I realized that many of the functionalities I had implemented already existed in reliable, community-maintained libraries, so I decided to refactor parts of the contract code to leverage these tools. The result was a cleaner and more readable contract. My intention in this post is to share how I refactored these parts and what improvements I achieved.

1. Financial Mathematics

The Previous Approach

The contract calculated interest amounts manually. Something like this:

// Calculate 2.37% commission (237 basis points)
let amount_to_commission = amount * 237 / (rate_denominator as i128) / 100 / 100; // Twice by 100 to downscale and apply %

// Calculate 5% reserve fund
let amount_to_reserve_fund = amount * 5 / 100;

// What remains for investment
let amount_to_invest = amount - amount_to_commission - amount_to_reserve_fund;

Amount {
    amount_to_invest,
    amount_to_reserve_fund,
    amount_to_commission,
}

The code worked, but it had a fundamental limitation: it performed calculations directly using the token's decimals (7 decimals in my case).

When you perform multiplication and division operations with integers in smart contracts, there can be cases (for example when many operations are chained) where you can lose precision due to integer rounding.

The New Approach: OpenZeppelin's WAD

WAD is a standard for fixed-point arithmetic with 18 decimals of precision. It's the same one used by DeFi on Ethereum, so there are years of battle-testing behind it.

// Now: Using WAD
use stellar_contract_utils::wad::Wad;

pub fn from_investment(e: &Env, amount: &i128, i_rate: &u32, decimals: u8) -> Amount {
    let rate_denominator: u32 = calculate_rate_denominator(&amount, decimals as u32);

    // Convert amount to WAD for high-precision calculations
    let amount_wad = Wad::from_token_amount(e, *amount, decimals);

    // Calculate commission rate as a precise ratio
    let commission_rate = Wad::from_ratio(
        e, 
        *i_rate as i128, 
        (rate_denominator as i128) * 10_000
    );

    // Reserve rate: 5%
    let reserve_rate = Wad::from_ratio(e, 5, 100);

    // Perform calculations with 18 decimals of precision
    let amount_to_commission_wad = amount_wad * commission_rate;
    let amount_to_reserve_fund_wad = amount_wad * reserve_rate;
    let amount_to_invest_wad = amount_wad - amount_to_commission_wad - amount_to_reserve_fund_wad;

    // Convert back to token amounts
    Amount {
        amount_to_commission: amount_to_commission_wad.to_token_amount(e, decimals),
        amount_to_reserve_fund: amount_to_reserve_fund_wad.to_token_amount(e, decimals),
        amount_to_invest: amount_to_invest_wad.to_token_amount(e, decimals),
    }
}

What Did We Improve?

Mathematical precision: WAD maintains 18 decimals, we only lose precision at the end.
Multi-token ready: Tokens with different decimals can coexist.
Battle-tested: Continuously maintained and improved by OpenZeppelin.

2. Access Control

The Previous Approach

I had my own access control system for admin-only functions:

// Before: Custom admin and manual validation
#[contracttype]
pub struct ContractData {
    pub admin: Address,  // ← Admin in the data
    pub project_address: Address,
    // ... more fields
}

// Helper function to validate admin
fn require_admin(env: &Env) -> ContractData {
    let contract_data = get_contract_data(env);
    contract_data.admin.require_auth();
    contract_data
}

// In each administrative function:
#[contractimpl]
impl InvestmentContract {
    pub fn single_withdrawn(env: Env, amount: i128) -> Result<bool, Error> {
        require_admin(&env); 
        // ... logic
    }
}

This is correct as it uses Soroban's authentication standard, but we can improve the code
with OpenZeppelin's Ownable module.

The New Approach: OpenZeppelin's Ownable Module

// Now: Using OpenZeppelin's Ownable
use stellar_access::ownable;
use stellar_macros::only_owner;
use soroban_ownable_macro::ownable;

#[contract]
pub struct InvestmentContract;

#[contractimpl]
impl InvestmentContract {
    pub fn __constructor(
        env: Env,
        owner_addr: Address,
        // ... more parameters
    ) {
        ownable::set_owner(&env, &owner_addr); // OpenZeppelin ownable
        // ... rest of setup
    }

    #[only_owner]  // ← Macro that validates automatically
    pub fn single_withdrawn(env: Env, amount: i128) -> Result<bool, Error> {
        // No need for require_admin() The macro handles it
        // ... logic
    }
}

What Did We Improve?

Simple ownership transfer: ownable::transfer_ownership() included.
Less code: I removed the require_admin() function and the macro does the work.

3. Pausing the Contract

The Original Approach

I had a Paused state in my enum and custom functions:

// Before: Custom pause state
#[contracttype]
pub enum State {
    Active = 2,
    FundsReached = 3,
    Paused = 4,  // ← Custom state
}

#[contracttype]
pub struct ContractData {
    pub state: State,
    // ...
}

// Functions to pause/resume
pub fn stop_investments(env: Env) -> Result<bool, Error> {
    let mut contract_data = require_admin(&env);
    require!(contract_data.state == State::Active, Error::ContractMustBeActiveToBePaused);

    contract_data.state = State::Paused;
    update_contract_data(&env, &contract_data);
    Ok(true)
}

pub fn restart_investments(env: Env) -> Result<bool, Error> {
    let mut contract_data = require_admin(&env);
    require!(contract_data.state == State::Paused, Error::ContractMustBePausedToRestartAgain);

    contract_data.state = State::Active;
    update_contract_data(&env, &contract_data);
    Ok(true)
}

// In invest(), manual validation:
pub fn invest(env: Env, addr: Address, amount: i128) -> Result<Investment, Error> {
    require!(contract_data.state == State::Active, Error::ContractMustBeActiveToInvest);
    // ...
}

These two functions simply mark the contract as "Paused" and later reactivate them, in addition to controlling that already paused contracts cannot be paused nor can already active contracts be reactivated. In the next section, we'll see how we can greatly reduce the code using OpenZeppelin's Pausable trait.

The New Approach: Pausable Trait

// Now: Using OpenZeppelin's Pausable
use stellar_contract_utils::pausable::{self as pausable, Pausable};
use stellar_macros::when_not_paused;

#[contract]
pub struct InvestmentContract;

// Implement the trait
#[contractimpl]
impl Pausable for InvestmentContract {
    #[only_owner]
    fn pause(e: &Env, _caller: Address) {
        pausable::pause(e);
    }

    #[only_owner]
    fn unpause(e: &Env, _caller: Address) {
        pausable::unpause(e);
    }
}

// Use the macro on sensitive functions
#[contractimpl]
impl InvestmentContract {
    #[when_not_paused]  // ← Macro that automatically verifies
    pub fn invest(env: Env, addr: Address, amount: i128) -> Result<Investment, Error> {
        // If paused, the macro automatically rejects the call
        // We only verify business logic

        require!(
            amount >= contract_data.min_per_investment, Error::AmountLessThanMinimum,
            tk.balance(&addr) >= amount, Error::AddressInsufficientBalance
        );
    }
}

Now the State enum only reflects business logic:

// Clean state: only business logic
#[contracttype]
pub enum State {
    Active = 2,        // Accepting investments
    FundsReached = 3,  // Goal reached
}

What Did We Improve?

Separation of concerns: Technical pause vs. business logic
Access control: #[when_not_paused] allows us to easily reject investments when the contract is paused without needing require.
Free queries: pausable::is_paused() included
Automatic events: OpenZeppelin emits Paused/Unpaused events

Conclusion

Modernizing code isn't admitting it was "wrong" before. It's recognizing that the industry evolves and there are better tools available, and that using them in your contracts or applications can make them more professional and standard.

If you're writing Soroban contracts, I recommend exploring OpenZeppelin before implementing custom logic. Not for all cases, but for common ones (mathematics, access control, pausing etc), there are already better solutions that can be very useful.

Note: If you want to see the complete code, you can access the repository "https://github.com/icolomina/soroban-contracts-examples/tree/main" and explore the open-zeppelin-utilities branch.

How Equillar Ensures Payment Capacity for Investment Contracts

Nacho Colomina Torregrosa — Sat, 10 Jan 2026 10:21:21 +0000

Introduction

One of the most critical aspects of any investment platform is ensuring that investors receive their payments reliably and on time. At Equillar, we have implemented an automated system that constantly verifies the payment capacity of each active investment contract. In this article, we will explore how this mechanism works internally.

Why is it important to verify payment capacity?

Imagine you have an active investment contract with multiple investors waiting for their monthly returns. The contract might be functioning correctly, receiving funds and processing operations, but what happens if at some point there aren't enough funds in the reserve to cover the next payments?

To avoid these types of situations as much as possible, we have opted for the following approach: we try to detect these problems before they occur, allowing organizations to take corrective action in time.

The verification flow: a three-phase architecture

Our payment capacity verification system operates in three phases, using an architecture based on commands, asynchronous messages, and concrete services.

Phase 1: Identifying contracts to verify

It all starts with a scheduled command that runs periodically:

php bin/console app:contract:check-payment-availability

This command (CheckContractPaymentAvailabilityCommand) is the entry point of our verification system. Its logic is simple and focused:

Selects eligible contracts: Not all contracts need constant verification. The command only searches for those in operational states:
- ACTIVE: Active contracts receiving investments
- FUNDS_REACHED: Contracts that reached their funding goal
- PAUSED: Contracts temporarily paused but still having payment obligations
Creates a verification record: For each selected contract, the system creates a ContractPaymentAvailability entity. This record acts as a verification "ticket" that stores:
- The contract to verify
- When the request was created
- The process status (pending, processed, failed)
- The verification results
Queues the work: Instead of processing everything synchronously (which could block the system for minutes), the command queues each verification as an asynchronous message through Symfony Messenger.

This design is important because it allows the command to finish quickly, while the heavy work is processed in the background. If you have 50 active contracts, the command simply creates 50 "tickets" and queues them, returning control in seconds.

Phase 2: Asynchronous processing

Once the messages are in the queue, Symfony Messenger workers come into play. Each message of type CheckContractPaymentAvailabilityMessage is processed by its corresponding handler (CheckContractPaymentAvailabilityMessageHandler).

The handler acts as a minimalist coordinator:

public function __invoke(CheckContractPaymentAvailabilityMessage $message): void
{
    $contractPaymentAvailability = $this->contractPaymentAvailabilityStorage
        ->getById($message->contractPaymentAvailabilityId);

    try {
        $this->contractCheckPaymentAvailabilityService
            ->checkContractAvailability($contractPaymentAvailability);
    } catch (ContractExecutionFailedException $e) {
        // The exception is handled silently because the state 
        // has already been recorded in the database
    }
}

This pattern of "delegating to the specialized service" is a good practice: the handler only deals with infrastructure (retrieving data, capturing errors), while the business logic lives in the service.

Phase 3: Blockchain interaction

This is where the most interesting part of the process occurs. The ContractCheckPaymentAvailabilityService is the core of our verification system, and it interacts directly with smart contracts on the Stellar blockchain.

The step-by-step process:

1. Smart contract invocation

The service calls a specific smart contract function (check_reserve_balance) that is deployed on the blockchain:

$trxResponse = $this->checkContractPaymentAvailabilityOperation
    ->checkContractPaymentAvailability($contractPaymentAvailability);

This smart contract function performs on-chain calculations: it checks how many investors there are, what the next pending payments are, how much is in the reserve fund, and calculates if there's a deficit.

The code for this function in the contract (written in Rust for Soroban) is as follows:

pub fn check_reserve_balance(env: Env) -> Result<i128, Error> {
    require_admin(&env);

    let claims_map: Map<Address, Claim> = get_claims_map_or_new(&env);
    let project_balances: ContractBalances = get_balances_or_new(&env);
    let mut min_funds: i128 = 0;

    for (_addr, next_claim) in claims_map.iter() {
        if next_claim.is_claim_next(&env) {
            min_funds += next_claim.amount_to_pay;
        }
    }

    if min_funds > 0 {
        if project_balances.reserve < min_funds {
            let diff_to_contribute: i128 = min_funds - project_balances.reserve;
            return Ok(diff_to_contribute);
        }
    }

    Ok(0_i128)
}

The function verifies that the caller is the administrator, then iterates over all pending claims to calculate the total minimum funds needed. If the reserve is insufficient, it returns the difference that needs to be contributed; otherwise, it returns 0.

You can check the complete contract code here: https://github.com/icolomina/soroban-contracts-examples/tree/main/investment

2. Result processing

The smart contract response comes in XDR format (a binary format used in Stellar), which we need to decode using the Soneso PHP Stellar SDK:

$trxResult = $this->scContractResultBuilder
    ->getResultDataFromTransactionResponse($trxResponse);

$requiredFunds = $this->i128Handler
    ->fromI128ToPhpFloat(
        $trxResult->getLo(), 
        $trxResult->getHi(), 
        $contractPaymentAvailability->getContract()->getToken()->getDecimals()
    );

The requiredFunds value is crucial: if it's 0, everything is fine. If it's greater than 0, it indicates exactly how much money is missing from the reserve fund to cover the next payments.

3. Transaction recording

Each blockchain interaction is recorded:

$contractTransaction = $this->contractTransactionEntityTransformer
    ->fromSuccessfulTransaction(
        $contractPaymentAvailability->getContract()->getAddress(),
        ContractNames::INVESTMENT->value,
        ContractFunctions::check_reserve_balance->name,
        [$trxResult],
        $trxResponse->getTxHash(),
        $trxResponse->getCreatedAt()
    );

This record (ContractTransaction) gives us:

Complete traceability: we can audit each verification
Transaction hash: we can verify it on Stellar
Exact timestamp: we know when it occurred
Result: what the smart contract returned

4. State update

If it's detected that funds are missing (requiredFunds > 0), the system takes immediate action:

if ($requiredFunds > 0) {
    $contract = $contractPaymentAvailability->getContract();
    $this->contractEntityTransformer->updateContractAsBlocked($contract);
    $this->persistor->persist($contract);
}

The contract moves to BLOCKED state, which:

Alerts administrators
Shows in the interface that the contract requires attention
Records exactly how much money needs to be added to the reserve fund

When viewing the contract details, the interface displays a warning message indicating the exact amount needed in the reserve fund. This is implemented in assets/react/controllers/Contract/ViewContract.tsx, which shows:

{query.data.requiredReserveFunds && query.data.requiredReserveFunds > 0 ? (
    <Typography variant="body1" fontWeight="medium" color="warning.main">
        ⚠️ The contract requires adding {formatCurrencyFromValueAndTokenContract(
            query.data.requiredReserveFunds, 
            query.data.tokenContract
        )} to the reserve fund to ensure investor payments.
    </Typography>
) : (
    <Typography variant="body1" fontWeight="medium" color="success.main">
        ✓ The contract has capacity to serve payments.
    </Typography>
)}

In future iterations, we plan to implement email notifications to alert administrators as soon as a deficit is detected.

5. Error handling

If something fails (network down, smart contract doesn't respond, execution error), the system records it in a controlled manner:

catch (TransactionExceptionInterface $ex) {
    $contractTransaction = $this->contractTransactionEntityTransformer
        ->fromFailedTransaction(
            $contractPaymentAvailability->getContract()->getAddress(),
            ContractNames::INVESTMENT->value,
            ContractFunctions::check_reserve_balance->name,
            $ex
        );

    // Mark the verification as failed
    $this->contractPaymentAvailabilityTransformer
        ->updateContractPaymentAvalabilityAsFailed(
            $contractPaymentAvailability, 
            $contractTransaction
        );
}

The ContractPaymentAvailability entity: the historical record

Each verification is documented in the database through the ContractPaymentAvailability entity. This entity acts as a historical record that stores:

class ContractPaymentAvailability
{
    private ?int $id;
    private ?Contract $contract;              // Which contract was verified?
    private ?float $requiredFunds;            // How much money is missing (if applicable)?
    private ?ContractTransaction $contractTransaction; // Associated blockchain transaction
    private ?\DateTimeImmutable $checkedAt;   // When was it verified?
    private ?\DateTimeImmutable $createdAt;   // When was it requested?
    private ?string $status;                  // Status: PENDING, PROCESSED, FAILED
}

This structure allows us to:

View the complete verification history of a contract
Identify patterns (does the contract run out of funds frequently?)
Measure processing times
Generate reports and metrics

Advantages of this architecture

1. Scalability

Asynchronous processing means we can verify many contracts without affecting the performance of the main application. Each verification is processed in its own context.

2. Resilience

If one verification fails, it doesn't affect the others. The system continues processing the rest of the contracts, and we can retry failed verifications later.

3. Transparency

By interacting with smart contracts on blockchain, the calculations are verifiable and immutable. Anyone can audit the smart contract logic.

4. Separation of concerns

The command handles identifying work
The handler handles messaging infrastructure
The service handles business logic
The entities handle the data model

Each component has a clear purpose and can evolve independently.

Conclusion

In this article, we've shown a hybrid solution (off-chain / on-chain) that combines Symfony with smart contract interaction to check the payment capacity of investment contracts. The off-chain component handles scheduling, queueing, and state management, while the on-chain component performs the actual financial calculations on the Stellar blockchain.

This approach allows us to leverage the best of both worlds: the flexibility and familiarity of a traditional PHP framework for business logic, and the transparency and immutability of blockchain for critical financial verifications.

In future articles, we will explore other aspects of the Equillar platform, such as payment processing, reserve fund management, and integration with the Stellar network. Stay tuned!

Technical note: This article describes the internal functioning of the system at the time of writing. Implementation details may evolve over time, but the fundamental architecture principles remain.

How Equillar Implements AEAD Encryption

Nacho Colomina Torregrosa — Wed, 31 Dec 2025 10:43:08 +0000

Introduction

I would like to share in this post an important change we've implemented in Equillar: migrating from SecretBox to AEAD (Authenticated Encryption with Associated Data) to protect sensitive data such as the private keys of the system wallets.

Why the Change?

Originally, Equillar used sodium_crypto_secretbox to encrypt sensitive data. It's a solid and proven algorithm, but after reading Stellar's security guide for web-based projects, we realized we could significantly improve our security by implementing AEAD.

SecretBox vs AEAD: What's the Difference?

Before diving into code, let's understand what we gain with this change:

SecretBox (what we had)

// Only encrypts the message
$cipher = sodium_crypto_secretbox($message, $nonce, $key);

Features:

✅ Encryption + authentication of the message
✅ Simple and fast
❌ Doesn't protect associated metadata
❌ Doesn't bind ciphertext to its context

Ideal use case: Encrypting a file without relevant metadata.

AEAD (what we implemented)

// Encrypts the message AND authenticates additional data
$cipher = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
    $message,
    $additionalData,  // ← The key difference
    $nonce,
    $key
);

Features:

✅ Encryption + authentication of the message.
✅ Authentication of Additional Data (AD) without encrypting it.
✅ Ciphertext is bound to its context.

Ideal use case: Encrypting a private key by binding it to the specific wallet that owns it.

Why Does This Matter?

Imagine an attacker compromises your database and obtains:

An encrypted private key from Wallet A
Data from Wallet B

With SecretBox: The attacker could try to use Wallet A's ciphertext in another context.

With AEAD: This is impossible. Wallet A's ciphertext is cryptographically bound to Wallet A's data. If you try to decrypt it with another AD, authentication automatically fails.

The Architecture: Schema Builders and Tagged Services

One of the challenges when implementing AEAD is generating Additional Data consistently and maintainably. Our solution: Schema Builders.

The Concept

Each entity that needs encryption has its own "builder" that constructs the Additional Data:

<?php

namespace App\Domain\Crypt\Aead\Service\Schema;

use App\Domain\Crypt\Aead\EntitySchemaBuilderInterface;
use App\Entity\SystemWallet;

class SystemWalletV1SchemaBuilder implements EntitySchemaBuilderInterface
{
    public function build(object $systemWallet): string
    {
        $adData = [
            'address'    => $systemWallet->getAddress(),
            'blockchain' => $systemWallet->getBlockchainNetwork()->getLabel(),
            'timestamp'  => $systemWallet->getCreatedAt()->getTimestamp(),
        ];

        ksort($adData);
        return json_encode($adData);
    }

    public function getEntityClass(): string
    {
        return SystemWallet::class;
    }

    public function getVersion(): string
    {
        return 'v1';
    }
}

Why do we version schemas? Because Additional Data must be exactly the same during encryption and decryption. If in the future we need to change what data we include, we create SystemWalletV2SchemaBuilder and maintain compatibility with old data.

Tagged Services: Symfony Auto-Registration

To manage multiple schema builders in a scalable way, we use Symfony Tagged Services. The interface has the #[AutoconfigureTag] attribute:

<?php

namespace App\Domain\Crypt\Aead;

use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag('app.crypt.aead_schema')]
interface EntitySchemaBuilderInterface
{
    public function build(object $entity): string;
    public function getEntityClass(): string;
    public function getVersion(): string;
}

This means that every class implementing the interface is automatically registered with the app.crypt.aead_schema tag.

Loading Schema Builders with a Configurator

To inject all tagged schema builders into the EntitySchemaBuilderLocator, we use a Symfony Service Configurator:

<?php

namespace App\Domain\Crypt\Aead\Service;

use Symfony\Component\DependencyInjection\Attribute\AutowireIterator;

class EntitySchemaBuilderLocatorConfigurator 
{
    public function __construct(
        #[AutowireIterator('app.crypt.aead_schema')]
        private readonly iterable $handlers
    ) {
    }

    public function configure(EntitySchemaBuilderLocator $locator): void
    {
        $collection = new EntitySchemaBuilderCollection();

        foreach($this->handlers as $schemaBuilder) {
            $collection->addSchemaBuilder($schemaBuilder);
        }

        $locator->setSchemaBuilders($collection);
    }
}

The configurator uses #[AutowireIterator] to automatically receive all services tagged with app.crypt.aead_schema, then builds the collection and injects it into the locator.

The EntitySchemaBuilderCollection organizes schema builders by entity class and version:

<?php

namespace App\Domain\Crypt\Aead\Service;

class EntitySchemaBuilderCollection 
{
    private array $schemaBuilders = [];

    public function addSchemaBuilder(EntitySchemaBuilderInterface $schema): void
    {
        // Organize by entity class
        if (!isset($this->schemaBuilders[$schema->getEntityClass()])) {
            $this->schemaBuilders[$schema->getEntityClass()] = [];
        }

        // Store by version
        $this->schemaBuilders[$schema->getEntityClass()][$schema->getVersion()] = $schema;
    }

    public function getLatestSchemaVersion(string $entity): ?EntitySchemaBuilderInterface 
    {
        if(!isset($this->schemaBuilders[$entity])) {
            return null;
        }

        $versions = $this->schemaBuilders[$entity];

        // Sort versions descending (v2, v1, etc.)
        uksort($versions, fn($a, $b) => version_compare($b, $a));

        return reset($versions);
    }

    public function getSchemaBuilder(string $entity, string $version): ?EntitySchemaBuilderInterface
    {
        return $this->schemaBuilders[$entity][$version] ?? null;
    }
}

This structure allows us to:

Store multiple versions of schemas for the same entity
Retrieve the latest version automatically with getLatestSchemaVersion()
Access specific versions for decrypting old data with getSchemaBuilder(entity, version)

Example: If you have SystemWalletV1SchemaBuilder and SystemWalletV2SchemaBuilder, both are stored under SystemWallet::class with keys 'v1' and 'v2'. When encrypting new data, we use v2. When decrypting old data, we use the version stored in the ciphertext metadata.

We register the configurator in config/services.yaml:

App\Domain\Crypt\Aead\Service\EntitySchemaBuilderLocator:
    configurator: ['@App\Domain\Crypt\Aead\Service\EntitySchemaBuilderLocatorConfigurator', 'configure']

Now the EntitySchemaBuilderLocator has access to all schema builders:

<?php

namespace App\Domain\Crypt\Aead\Service;

use App\Domain\Crypt\Aead\EntitySchemaBuilderInterface;

class EntitySchemaBuilderLocator
{
    public function __construct(
        private readonly EntitySchemaBuilderCollection $schemaBuilders
    ) {
    }

    public function getLatestSchemaBuilder(string $entityClass): ?EntitySchemaBuilderInterface
    {
        return $this->schemaBuilders->getLatestSchemaVersion($entityClass);
    }

    public function getSchemaBuilder(string $schema, string $version): ?EntitySchemaBuilderInterface
    {
        return $this->schemaBuilders->getSchemaBuilder($schema, $version);
    }
}

Advantage: When you add a new schema builder, you simply implement the interface and it's already available. The configurator automatically collects and injects all tagged services, no manual configuration needed.

AeadEncryptor: The Heart of the System

Now comes the interesting part: how we encrypt using AEAD with key derivation.

Why Derive Keys?

Instead of directly using the master key for each encryption, we derive a unique subkey based on the Additional Data. This adds an extra layer of security: even if two entities have the same data, each encryption uses a different subkey (thanks to the random context).

<?php

namespace App\Domain\Crypt\Aead\Service;

class AeadEncryptor
{
    public function encryptMsg(
        string $value, 
        string $additionalData, 
        string $schema, 
        string $version
    ): AeadCryptedValue {
        // 1. Generate random nonce
        $nonce = random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES);

        // 2. Derive subkey ID from Additional Data hash
        $hash = sodium_crypto_generichash($additionalData, '', SODIUM_CRYPTO_GENERICHASH_BYTES_MIN);
        ['id' => $subkeyId] = unpack('Jid', $hash);
        $subkeyId = $subkeyId & 0x7FFFFFFFFFFFFFFF; // Force positive

        // 3. Generate random context for KDF
        $context = random_bytes(SODIUM_CRYPTO_KDF_CONTEXTBYTES);

        // 4. Derive the subkey
        $derivedKey = $this->deriveKeyFromSubkeyId($subkeyId, $context);

        // 5. Encrypt with AEAD
        $cipher = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
            $value,
            $additionalData,
            $nonce,
            $derivedKey
        );

        sodium_memzero($derivedKey); // Clear memory

        return new AeadCryptedValue(
            base64_encode($cipher),
            base64_encode($nonce),
            $schema,
            $version,
            CryptEngine::AEAD->value,
            $this->key->id,
            base64_encode($context),
            $subkeyId
        );
    }

    private function deriveKeyFromSubkeyId(int $subkeyId, string $context): string
    {
        return sodium_crypto_kdf_derive_from_key(
            SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES,
            $subkeyId,
            $context,
            $this->encryptionKey
        );
    }
}

Encryption Flow Step by Step:

Random nonce (24 bytes): Ensures each encryption is unique
SubkeyId derived from AD: BLAKE2b hash of Additional Data → 64-bit integer
Random context (8 bytes): Input for KDF, stored with ciphertext
Key derivation: sodium_crypto_kdf_derive_from_key(subkeyId, context, masterKey)
AEAD encryption: XChaCha20-Poly1305-IETF with authenticated AD
Memory cleanup: sodium_memzero() to erase the derived subkey

Decryption: The Reverse Path

public function decryptMsg(AeadCryptedValue $aeadCryptedValue, string $additionalData): string 
{
    $cipher = base64_decode($aeadCryptedValue->ciphertext, true);
    $nonce  = base64_decode($aeadCryptedValue->nonce, true);
    $context = base64_decode($aeadCryptedValue->context, true);

    // Derive the same subkey using stored subkeyId and context
    $derivedKey = $this->deriveKeyFromSubkeyId(
        $aeadCryptedValue->subkeyId, 
        $context
    );

    // Decrypt while verifying Additional Data
    $plain = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
        $cipher,
        $additionalData,
        $nonce,
        $derivedKey
    );

    sodium_memzero($derivedKey);

    if ($plain === false) {
        throw new \RuntimeException(
            'Decryption or authentication failed. Data may have been tampered with.'
        );
    }

    return $plain;
}

Key Points:

The subkeyId and context are stored with the ciphertext
The Additional Data must be exactly the same as during encryption
If AD, nonce, context, or ciphertext are modified, authentication fails

EntityAeadEncryptor: The Application Layer

Finally, we need a service that brings everything together: schema builders + AEAD encryptor. This is EntityAeadEncryptor:

<?php

namespace App\Domain\Crypt\Aead\Service;

use App\Domain\Crypt\Aead\AeadCryptedValue;
use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;

class EntityAeadEncryptor
{
    public function __construct(
        private readonly EntitySchemaBuilderLocator $schemaBuilderLocator,
        private readonly AeadEncryptor $aeadEncryptor,
        private readonly DenormalizerInterface $serializer
    ) {
    }

    public function encryptEntity(object $entity, string $plain): AeadCryptedValue
    {
        // 1. Get the appropriate schema builder
        $schemaBuilder = $this->schemaBuilderLocator
            ->getLatestSchemaBuilder($entity::class);

        if ($schemaBuilder === null) {
            throw new \RuntimeException(
                'No schema builder found for entity: ' . $entity::class
            );
        }

        // 2. Build Additional Data
        $associatedData = $schemaBuilder->build($entity);

        // 3. Encrypt
        return $this->aeadEncryptor->encryptMsg(
            $plain, 
            $associatedData, 
            $schemaBuilder->getEntityClass(),
            $schemaBuilder->getVersion()
        );
    }

    public function decryptEntity(
        object $entity, 
        array|AeadCryptedValue $cryptedValue
    ): string {
        // Support both AeadCryptedValue and array (from DB)
        $cryptedValue = ($cryptedValue instanceof AeadCryptedValue) 
            ? $cryptedValue
            : $this->serializer->denormalize($cryptedValue, AeadCryptedValue::class);

        // 1. Get the schema builder by version
        $schemaBuilder = $this->schemaBuilderLocator->getSchemaBuilder(
            $cryptedValue->schema, 
            $cryptedValue->version
        );

        if ($schemaBuilder === null) {
            throw new \RuntimeException(
                'No schema builder found for entity: ' . 
                $cryptedValue->schema . ' version: ' . $cryptedValue->version
            );
        }

        // 2. Rebuild the same Additional Data
        $associatedData = $schemaBuilder->build($entity);

        // 3. Decrypt
        return $this->aeadEncryptor->decryptMsg($cryptedValue, $associatedData);
    }
}

Usage in Practice

This is how we encrypt a SystemWallet's private key:

// Create wallet
$systemWallet = new SystemWallet();
$systemWallet->setAddress($stellarAddress);
$systemWallet->setBlockchainNetwork($blockchainNetwork);
$systemWallet->setCreatedAt(new \DateTimeImmutable());

// Persist first (we need complete fields for AD)
$entityManager->persist($systemWallet);
$entityManager->flush();

// Encrypt the private key bound to the wallet
$cryptedValue = $entityAeadEncryptor->encryptEntity(
    $systemWallet, 
    $secretSeed
);

// Save the encrypted result
$systemWallet->setPrivateKey($this->serializer->normalize($cryptedValue));
$entityManager->flush();

And to decrypt:

// Retrieve wallet from DB
$systemWallet = $systemWalletRepository->find($id);

// Decrypt (automatically validates that AD matches)
$secretSeed = $entityAeadEncryptor->decryptEntity(
    $systemWallet,
    $systemWallet->getPrivateKey()
);

// Use the private key
$keyPair = KeyPair::fromSeed($secretSeed);

Advantages of This Architecture

✅ Enhanced security: Encrypted data is bound to its context

✅ Versioning: We can evolve schemas without breaking old data

✅ Scalable: Adding encryption to new entities is trivial

✅ Separation of Concerns: Schema builders, encryption, and application layers are decoupled

✅ Testable: Each layer can be tested independently

✅ Tagged Services: Auto-registration of schema builders without manual configuration

Testing: Validating Security

Of course, we've created comprehensive tests to validate everything works correctly:

public function testDecryptionFailsWithDifferentEntity(): void
{
    $systemWallet1 = EntityGenerator::systemWallet();
    $systemWallet2 = EntityGenerator::systemWallet();
    $plaintext = 'secret_data';

    // Encrypt with first wallet
    $encrypted = $this->entityAeadEncryptor->encryptEntity(
        $systemWallet1, 
        $plaintext
    );

    // Try to decrypt with second wallet (different AD)
    $this->expectException(\RuntimeException::class);
    $this->expectExceptionMessage('Decryption or authentication failed');

    $this->entityAeadEncryptor->decryptEntity($systemWallet2, $encrypted);
}

This test confirms that you cannot decrypt data from one wallet using another wallet's context, even if you have access to the ciphertext.

Conclusion

Migrating from SecretBox to AEAD was a decision motivated by following the security best practices recommended by Stellar. The result is a more robust system that:

Protects sensitive data by cryptographically binding it to its context
Is maintainable and scalable thanks to schema builders
Allows evolution without breaking compatibility through versioning
Uses key derivation to add an extra layer of security

If you're developing on Stellar and handling sensitive data, I strongly recommend reading the Securing Web-Based Projects guide and considering AEAD for your project.

The complete code is available in the Equillar repository under the AGPL-3.0 license.

How Equillar Uses Stellar Muxed Accounts

Nacho Colomina Torregrosa — Sat, 13 Dec 2025 14:15:14 +0000

Introduction

If you've worked with blockchain payments, you've likely encountered this classic problem: how do you know which payment corresponds to which user or project when everyone sends funds to the same address? In Stellar, the traditional solution has been to use memos, but today we'll tell you how Equillar has evolved toward a more elegant and secure approach using Stellar Muxed Accounts.

The Previous System: Memo-Based Management

Before implementing Muxed Accounts, reserve fund contributions in Equillar followed a workflow that, while functional, required several manual steps and coordination from the user:

Memo-Based Flow

Contribution request

The user (the company) requested to make a contribution to the reserve fund through the platform.

Identifier generation

The system created a record in the database with the details of the requested contribution and generated a unique identifier for that specific contribution.

Instructions to the user

The user was shown:

The generated identifier.
The system's global address where funds should be sent.
Instructions to include the identifier as a Memo in the transaction.

Sending funds

The user performed the transaction from their wallet, exchange, or other means, including the identifier as a memo.

Verification and processing

A periodic process in the system searched for incoming transactions and verified:

That the transaction's memo matched a pending contribution record.
That the transaction came from the registered address set by the company for that project.
That the amount was equal to or greater than what was registered in the request.

Transfer to contract

If all validations were successful, the system extracted the corresponding contract from the contribution record and transferred the amount to the smart-contract using the appropriate function.

Limitations of this approach

While functional, this system had several drawbacks:

Mandatory pre-registration: You couldn't simply "send funds" to the project; you had to first create a request on the platform
Error risk: If the user forgot to include the memo or wrote it incorrectly, the funds would be in limbo
Reconciliation complexity: The system had to maintain a correspondence mapping between identifiers, memos, and contracts

The New System: Muxed Accounts

Stellar's Muxed Accounts have allowed us to simplify this flow, eliminating virtually all friction for the user while maintaining (and even improving) security and traceability.

What Are Muxed Accounts?

A Muxed Account is a virtual address derived from a real Stellar address. Think of it as a "subaccount" that points to the same base address but with a unique identifier embedded. Visually, a muxed account has the format M... instead of the classic G... of common Stellar addresses.

The magic is that you can generate multiple muxed accounts from a single Stellar address, and the protocol allows you to automatically distinguish which one a transaction was sent to.

The Soneso PHP Stellar SDK, that is actively used in Equillar, allows developers to easily use and manage Stellar Muxed Accounts.

Implementation in Equillar

Muxed Account Generation per Contract

When a contract is activated in Equillar, it is automatically assigned a unique muxed account. This occurs in the ContractActivationService:

// After successfully activating the contract...
$muxedId      = $this->contractMuxedIdGenerator->generateMuxedId($contract);
$muxedAccount = $this->stellarAccountLoader->generateMuxedAccount($muxedId);

$this->contractEntityTransformer->updateContractWithMuxedAccount($contract, $muxedAccount, $muxedId);
$this->persistor->persistAndFlush([$contractTransaction, $contract]);

The muxed account ID is generated by combining the organization ID and the contract ID:

public function generateMuxedId(Contract $contract): int
{
    $orgId        = $contract->getOrganzation()->getId();
    $contractId   = $contract->getId();

    $muxedId = $orgId * $contractId;

    // Range validations...
    return $muxedId;
}

This strategy ensures that each contract has a unique ID without collisions.

Simplified User Interface

The user experience has been radically simplified. Now, when they want to make a contribution to the reserve fund, they simply:

Click on the reserve fund contribution button
A modal opens (CreateReserveFundContributionModal) displaying the contract's muxed address
The user copies that address and sends the funds directly

<Typography variant="body1" sx={{ mt: 2, mb: 3, textAlign: 'center' }}>
    To make a contribution to the reserve fund, simply transfer the desired 
    amount to the following address:
</Typography>

<Box sx={{ /* ... */ }}>
    <Typography variant="body2" sx={{ /* ... */ }}>
        {props.contract.muxedAccount}
    </Typography>
    <IconButton onClick={handleCopyAddress}>
        <ContentCopyIcon />
    </IconButton>
</Box>

No forms to fill out, no need to remember to include a memo, no identifiers to manually copy. Just an address to send funds to.

Automatic Contribution Processing

The ContractCheckReserveFundContributionsCommand runs periodically to detect and process incoming contributions. The ContractReserveFundContributionsProcessorService does the heavy lifting:

public function processIncomingContributons(): array
{
    $contributionsResult = [];
    $sdk = $this->stellarAccountLoader->getSdk();

    // Gets the last 10 payment transactions to the system account
    $operationsResponse = $sdk
        ->payments()
        ->includeTransactions(true)
        ->forAccount($this->stellarAccountLoader->getAccount()->getAccountId())
        ->order('desc')
        ->limit(10)
        ->execute();

    foreach ($operationsResponse->getOperations() as $payment) {
        // Validations...

        $destinationMuxedAccount = $payment->getToMuxed();

        // Finds the contract associated with this muxed account
        $contract = $this->contractStorage->getContractByMuxedAccount($destinationMuxedAccount);

        // Validates that the source address is the one registered for the project
        if ($contract->getProjectAddress() !== $sourceAccount) {
            $contributionsResult[$payment->getTransactionHash()] = 
                ContractProcessIncomingContributionsResult::fromUnmatchingSourceAccountAndProjectAddress();
            continue;
        }

        // More validations and processing...
    }
}

The process performs several critical validations:

Check for a successful transaction

Only processes payments that completed successfully on the blockchain:

if (!$payment->isTransactionSuccessful()) {
    $contributionsResult[$payment->getTransactionHash()] = 
        ContractProcessIncomingContributionsResult::fromInvalidTransaction();
    continue;
}

Valid Operation Type

Verifies that it's a payment operation (not another type of Stellar operation):

if(!$payment instanceof PaymentOperationResponse) {
    continue;
}

Muxed Account Present

Verifies that the transaction was sent to a muxed account (not to the base address):

$destinationMuxedAccount = $payment->getToMuxed();

if (!$destinationMuxedAccount) {
    $contributionsResult[$payment->getTransactionHash()] = 
        ContractProcessIncomingContributionsResult::fromEmptyDestinationMuxedAccount();
    continue;
}

Existing Contract

Finds the contract associated with that specific muxed account:

$contract = $this->contractStorage->getContractByMuxedAccount($destinationMuxedAccount);

If no contract exists with that muxed account, the search will throw an exception or return null, preventing the processing of payments to addresses not associated with projects.

Verified Origin

Confirms that the payment comes from the address registered by the company (security):

$sourceAccount = $payment->getSourceAccount();

if ($contract->getProjectAddress() !== $sourceAccount) {
    $contributionsResult[$payment->getTransactionHash()] = 
        ContractProcessIncomingContributionsResult::fromUnmatchingSourceAccountAndProjectAddress();
    continue;
}

This validation is crucial: it prevents anyone from sending arbitrary funds to the project. Only the authorized address can make valid contributions.

No Duplicates

Verifies that the transaction has not been previously processed:

$existingContribution = $this->contractReserveFundContributionStorage
    ->getByPaymentTransactionHash($payment->getTransactionHash());

if ($existingContribution) {
    $contributionsResult[$payment->getTransactionHash()] = 
        ContractProcessIncomingContributionsResult::fromContributionAlreadyProcessed();
    continue;
}

Sufficient Balance

Ensures that the system has enough contract token balance in the account to manage the transfer to the contract:

$tokenBalance = $this->stellarAccountLoader->getTokenBalance($contract->getToken());

if($tokenBalance < (float) $payment->getAmount()) {
    $contributionsResult[$payment->getTransactionHash()] = 
        ContractProcessIncomingContributionsResult::fromSystemAddressNotHoldingEnougthBalance();
    continue;
}

If all validations pass, the system proceeds with:

// 1. Creates a contribution record
$contractReserveFundContribution = $this->contractReserveFundContributionTransformer
    ->fromContractAndAmountToEntity(
        $contract,
        $payment->getTransactionHash(),
        (float) $payment->getAmount()
    );

// 2. Persists the record in the database
$this->persistor->persistAndFlush($contractReserveFundContribution);

// 3. Calls the smart contract function to transfer funds to the reserve fund
$this->contractReserveFundContributionTransferService
    ->processReserveFundContribution($contractReserveFundContribution);

// 4. Marks the contribution as successfully processed
$contributionsResult[$payment->getTransactionHash()] = 
    ContractProcessIncomingContributionsResult::fromProcessed();

Technical Considerations

ID Generation

Our strategy of multiplying orgId * contractId to generate the muxed ID is simple but effective. Since both organization IDs and contract IDs are sequential and unique, the product will always be unique.

However, it's important to consider range limitations. In our case, we validate that the generated ID is between 1 and 2,147,483,647 (PostgreSQL's INT4_MAX).

Limit Constraint When Calling Horizon API

The current processing command queries the last 10 transactions. In a system with high transaction volume, this limit might need to be dynamically adjusted or implement a cursor to paginate results.

$operationsResponse = $sdk
    ->payments()
    ->includeTransactions(true)
    ->forAccount($this->stellarAccountLoader->getAccount()->getAccountId())
    ->order('desc')
    ->limit(10)  // ← Might need adjustment, paginating or using streams
    ->execute();

Conclusion

The adoption of Muxed Accounts in Equillar represents much more than a simple technical change: it's a fundamental improvement in user experience that eliminates friction, reduces errors, and simplifies the system architecture.

While the memo-based system worked, it required manual coordination and multiple steps that could go wrong. Muxed Accounts allow us to leverage a native feature of the Stellar protocol to provide a more fluid and natural user experience.

If you're building an application that needs to receive differentiated payments to the same base account, you should definitely consider Muxed Accounts. We hope this article inspires you to explore their possibilities in your own projects.

Have questions about our implementation or want to know more about how we use Stellar in Equillar? Don't hesitate to contact us or check out our open source code.

From Blockchain to Database: Synchronizing Soroban with PHP

Nacho Colomina Torregrosa — Sun, 07 Dec 2025 09:49:51 +0000

Introduction

One of the most interesting challenges when working with blockchain is maintaining precise synchronization between on-chain transactions and our off-chain system. In this article, I'll share how i've solved this challenge in Equillar: how I convert the result of a Soroban smart contract call into a PHP Doctrine entity, achieving an exact replica of the blockchain state in our database.

The Journey of a Transaction

Imagine a user wants to create an investment. From the moment they click the button until the data is perfectly stored in our database, a chain of events takes place. Let's follow that flow step by step.

1. The Entry Point: The Controller

Everything begins in the createUserContract endpoint:

#[Route('/create-user-investment', name: 'post_create_user_contract_investment', methods: ['POST'])]
#[IsGranted('ROLE_USER')]
public function createUserContract(
    #[MapRequestPayload] CreateUserContractDtoInput $createUserContractDtoInput, 
    CreateUserContractService $createUserContractService
): JsonResponse
{
    $user = $this->getUser();
    return $this->json($createUserContractService->createUserContract($createUserContractDtoInput, $user));
}

Simple and straightforward: we receive the user's data, validate they're authenticated, and delegate the business logic to the corresponding service.

2. Setting the Stage: CreateUserContractService

The CreateUserContractService service has a clear mission: prepare all the pieces before executing the blockchain transaction.

public function createUserContract(CreateUserContractDtoInput $createUserContractDtoInput, User $user): UserContractDtoOutput
{
    // 1. Get the contract from the blockchain by its address
    $contract = $this->contractStorage->getContractByAddress(
        StrKey::decodeContractIdHex($createUserContractDtoInput->contractAddress)
    );

    // 2. Verify or create the user's wallet
    $userWallet = $this->userWalletStorage->getWalletByAddress($createUserContractDtoInput->fromAddress);
    if(!$userWallet) {
        $userWallet = $this->userWalletEntityTransformer->fromUserAndAddressToUserWalletEntity(
            $user, 
            $createUserContractDtoInput->fromAddress
        );
        $this->persistor->persist($userWallet);
    }

    // 3. Create the UserContract entity (still without smart contract data)
    $userContract = $this->userContractEntityTransformer->fromCreateUserContractInvestmentDtoToEntity(
        $createUserContractDtoInput, 
        $contract, 
        $userWallet
    );
    $this->persistor->persist($userContract);
    $this->persistor->flush();

    // 4. (This is the blockchain part) - Process the blockchain transaction
    $this->processUserContractService->processUserContractTransaction($userContract);

    return $this->userContractEntityTransformer->fromEntityToOutputDto($userContract);
}

At this point, we've created the record in our database, but it still doesn't contain the real blockchain data.

3. The Smart Contract Call: ProcessUserContractService

This is where we actually connect with the Stellar/Soroban blockchain:

public function processUserContractTransaction(UserContract $userContract): void
{
    $contractTransaction = null;

    try {
        // 1. Wait for the transaction to be confirmed on the blockchain
        $transactionResponse = $this->processTransactionService->waitForTransaction($userContract->getHash());

        // 2. Use Soneso / PHP Stellar SDK to transform XDR transacion result to PHP types
        $trxResult = $this->scContractResultBuilder->getResultDataFromTransactionResponse($transactionResponse);

        // 3. Map the result to our entity
        $this->userInvestmentTrxResultMapper->mapToEntity($trxResult, $userContract);

        // 4. Save the successful transaction
        $contractTransaction = $this->contractTransactionEntityTransformer->fromSuccessfulTransaction(
            $userContract->getContract()->getAddress(),
            ContractNames::INVESTMENT->value,
            ContractFunctions::invest->name,
            $trxResult,
            $transactionResponse->getTxHash(),
            $transactionResponse->getCreatedAt()
        );

        // 5. Dispatch an event to update the contract balance
        $this->bus->dispatch(new CheckContractBalanceMessage(
            $userContract->getContract()->getId(), 
            $transactionResponse->getLedger()
        ));

    } catch (GetTransactionException $ex) {
        // If something goes wrong, log the error
        $userContract->setStatus($ex->getStatus());
        $contractTransaction = $this->contractTransactionEntityTransformer->fromFailedTransaction(
            $userContract->getContract()->getAddress(),
            ContractNames::INVESTMENT->value,
            ContractFunctions::invest->name,
            $ex
        );
    } finally {
        // Always persist the final state
        $this->persistor->persistAndFlush([$userContract, $contractTransaction]);
    }
}

4. Waiting for Confirmation: waitForTransaction

The blockchain isn't instantaneous. When we send a transaction, it must be included in a ledger and confirmed. The waitForTransaction method implements a polling system:

public function waitForTransaction(string $hash, int $maxIterations = 10, ?int $microseconds = null): GetTransactionResponse
{
    $counter = 0;
    do {
        // Wait a moment between each check
        ($microseconds > 0) ? usleep($microseconds) : sleep(1);

        // Query the transaction status
        $transactionResponse = $this->server->getTransaction($hash);
        $status = $transactionResponse->status;
        ++$counter;

    } while ($counter < $maxIterations && 
             !in_array($status, [GetTransactionResponse::STATUS_SUCCESS, GetTransactionResponse::STATUS_FAILED]));

    if (GetTransactionResponse::STATUS_SUCCESS !== $status) {
        throw new GetTransactionException($transactionResponse);
    }

    return $transactionResponse;
}

This pattern is crucial: we repeatedly check the status until the transaction is confirmed or fails. It's like refreshing package tracking until we see "Delivered".

5. Decoding XDR: ScContractResultBuilder

When the smart contract responds, it does so in a format called XDR (External Data Representation), a serialization standard used in Stellar. We need to translate this format into something PHP can understand.

For this task, we rely on the Soneso Stellar PHP SDK, which provides all the necessary tools to decode XDR structures into native PHP types:

public function getResultDataFromTransactionResponse(GetTransactionResponse $transactionResponse): mixed
{
    $xdrResult = $transactionResponse->getResultValue();
    return $this->getValueFromXdrResult($xdrResult, $transactionResponse->getTxHash());
}

private function getValueFromXdrResult(XdrSCVal $xdrResult, string $hash): mixed
{
    return match ($xdrResult->type->value) {
        XdrSCValType::SCV_VOID => null,
        XdrSCValType::SCV_BOOL => $xdrResult->getB(),
        XdrSCValType::SCV_ERROR => $this->processFunctionCallError($xdrResult->getError(), $hash),
        XdrSCValType::SCV_I128 => $xdrResult->getI128(),
        XdrSCValType::SCV_MAP => $this->generateForMap($xdrResult->getMap()),  // This is the key!
        XdrSCValType::SCV_U32 => $xdrResult->getU32(),
        XdrSCValType::SCV_STRING => $xdrResult->getStr(),
        default => $xdrResult->encode(),
    };
}

The Soneso SDK provides the XdrSCVal class that represents Soroban smart contract values, along with methods to extract each type safely. In our case, the smart contract returns a map (type SCV_MAP) with key-value pairs containing all the investment information:

private function generateForMap(array $map): array
{
    $entryMap = [];
    foreach ($map as $entry) {
        $value = match ($entry->val->type->value) {
            XdrSCValType::SCV_I128 => $entry->val->getI128(),  // Large numbers (128 bits)
            XdrSCValType::SCV_U64 => $entry->val->getU64(),    // Timestamps
            XdrSCValType::SCV_U32 => $entry->val->getU32(),    // Small numbers
            XdrSCValType::SCV_STRING => $entry->val->getStr(), // Text strings
            default => null,
        };

        $entryMap[$entry->key->sym] = $value;
    }

    return $entryMap;
}

The result is a PHP associative array with keys like 'deposited', 'accumulated_interests', 'status', etc.

6. The Final Mapping: UserInvestmentTrxResultMapper

This is the piece that closes the circle. We take the contract data array and convert it into properties of our Doctrine entity:

public function mapToEntity(array $trxResult, UserContract $userContract): void
{
    $decimals = $userContract->getContract()->getToken()->getDecimals();

    foreach ($trxResult as $key => $value) {
        // Process each value according to its type
        $result = match ($key) {
            // Monetary amounts: convert from I128 to PHP decimal
            'accumulated_interests', 'deposited', 'total', 'paid', 'regular_payment', 'commission' => 
                I128::fromLoAndHi($value->getLo(), $value->getHi())->toPhp($decimals),

            // Timestamp of when it can be claimed
            'claimable_ts' => $value,

            // Last payment: convert UNIX timestamp to DateTime
            'last_transfer_ts' => ($value > 0) 
                ? new \DateTimeImmutable(date('Y-m-d H:i:s', $value)) 
                : null,

            // Contract status: convert number to enum
            'status' => (UserContractStatus::tryFrom($value) ?? UserContractStatus::UNKNOWN)->name,

            default => null,
        };

        // Assign the value to the entity
        $this->setValueToEntity($userContract, $key, $result);
    }
}

private function setValueToEntity(UserContract $userContract, string $key, mixed $value): void
{
    $currentTotalCharged = $userContract->getTotalCharged() ?? 0;

    match ($key) {
        'accumulated_interests' => $userContract->setInterests($value),
        'commission' => $userContract->setCommission($value),
        'deposited' => $userContract->setBalance($value),
        'total' => $userContract->setTotal($value),
        'claimable_ts' => $userContract->setClaimableTs($value),
        'last_transfer_ts' => $userContract->setLastPaymentReceivedAt($value),
        'paid' => $userContract->setTotalCharged($currentTotalCharged + $value),
        'status' => $userContract->setStatus($value),
        'regular_payment' => $userContract->setRegularPayment($value),
        default => null,
    };
}

The Complete Flow in Perspective

Let's see the entire process at a glance:

API Request → The user sends their investment data
Validation and Preparation → We verify the contract and wallet
Base Entity Creation → We save an initial record in the DB
Transaction Wait → We wait for Soroban confirmation
XDR Decoding → We convert blockchain format to PHP
Data Mapping → We transform the result into entity properties
Final Persistence → We save the complete state in the database

Important Technical Details

Handling Large Numbers (I128)

Soroban uses 128-bit numbers to represent amounts with decimals. We can't use PHP's native types directly, so we have an I128 class that converts them:

I128::fromLoAndHi($value->getLo(), $value->getHi())->toPhp($decimals)

This takes the high and low parts of the 128-bit number and converts them to a PHP float, applying the token's decimals.

Timestamps and Dates

Soroban returns UNIX timestamps (seconds since 1970). We convert them to PHP DateTimeImmutable objects:

new \DateTimeImmutable(date('Y-m-d H:i:s', $value))

States as Enums

The contract status comes as a number, but in PHP we want it as a readable enum:

(UserContractStatus::tryFrom($value) ?? UserContractStatus::UNKNOWN)->name

Advantages of This Approach

Separation of Concerns: Each class has a single, well-defined responsibility
Testability: We can mock each step of the process
Resilience: If the transaction fails, we capture and log the error
Traceability: We save both successful and failed transactions
Consistency: The database always reflects the real state of the blockchain

Conclusion

Synchronizing a blockchain with a traditional database is not trivial, but with a well-thought-out architecture it's completely manageable. The key is:

Patiently waiting for transaction confirmation
Correctly decoding the XDR format with the help of the Soneso SDK
Systematically mapping each field to its counterpart in the entity
Robustly handling errors

This pattern has worked perfectly for us to keep our off-chain system perfectly synchronized with Soroban. I hope it's useful if you're working on something similar.

How equillar manage investment commissions

Nacho Colomina Torregrosa — Sun, 23 Nov 2025 10:06:01 +0000

How equillar manage investment commissions

When creating the equillar smart-contract, one of the most important decisions was how to structure commissions. Instead of applying a single fixed percentage, we have implemented a dynamic commission system that rewards larger investments with lower rates. This approach incentivizes significant capital contributions while maintaining a fair and accessible base rate for smaller investors.

The Philosophy: Decreasing Commissions

The central idea of our system is simple: the more you invest, the lower the commission percentage you pay. This approach has several benefits:

Accessibility: Small investors aren't penalized with disproportionate commissions
Incentive: Encourages larger investments by offering better conditions
Fairness: Balances operational costs with fair treatment for everyone

The Rate Denominator

To implement this dynamic system, we use a variable called the rate denominator. This is the key piece that makes commissions adjust automatically. Let's explore how it works

The calculate_rate_denominator function

Here's the actual contract code that calculates the rate denominator:

pub(self) const LOWER_AMOUNT_FOR_COMMISSION_REDUCTION: i128 = 100;
pub(self) const LOWER_DIVISOR: u32 = 10;
pub(self) const UPPER_DIVISOR: u32 = 60;
pub(self) const AMOUNT_PER_COMMISSION_REDUCTION: i128 = 400; 

pub fn calculate_rate_denominator(amount: &i128, decimals: u32) -> u32 {
    let scale_factor = 10_i128.pow(decimals);
    let token_amount = amount / scale_factor;

    if token_amount <= LOWER_AMOUNT_FOR_COMMISSION_REDUCTION {
        return LOWER_DIVISOR;
    }

    let a = (token_amount - LOWER_AMOUNT_FOR_COMMISSION_REDUCTION) 
            / AMOUNT_PER_COMMISSION_REDUCTION;

    if a > UPPER_DIVISOR as i128 {
        return UPPER_DIVISOR;
    }

    LOWER_DIVISOR + a as u32
}

Let's break down how calculate_rate_denominator works step by step:

Decimal Handling (Lines 1-4)

let scale_factor = 10_i128.pow(decimals);
let token_amount = amount / scale_factor;

First, the function converts the scaled amount (e.g., 3,600,000,000 for a token with 7 decimals such as USDC) to real token units (360). This is crucial because blockchain contracts receive amounts scaled by the token's decimals, but our logic needs to work with actual token quantities.

Base Tier Check (Lines 6-8)

if token_amount <= LOWER_AMOUNT_FOR_COMMISSION_REDUCTION {
    return LOWER_DIVISOR;
}

If the investment is 100 tokens or less, we immediately return a rate denominator of 10. This is the "base" tier where all small investors are treated equally.

Tiered Calculation (Lines 10-11)

let a = (token_amount - LOWER_AMOUNT_FOR_COMMISSION_REDUCTION) / AMOUNT_PER_COMMISSION_REDUCTION;

For investments above 100 tokens, we calculate how many 400-token tiers the investment spans:

First 100 tokens: Covered by base tier (rate denominator = 10)
Tokens 101-500: Still rate denominator = 10 (excess < 400, so 0 additional tiers)
Tokens 501-900: Rate denominator = 11 (excess ≥ 400, so +1 tier)
Tokens 901-1,300: Rate denominator = 12 (excess ≥ 800, so +2 tiers)
And so on...

This creates a tiered structure where every complete 400-token tier above the base reduces the commission percentage.

Maximum Cap (Lines 13-15)

if a > UPPER_DIVISOR as i128 {
    return UPPER_DIVISOR;
}

We cap the rate denominator at 60 to prevent commissions from becoming unreasonably small. Even ultra-large investments (millions of tokens) will use a denominator of 60, which already provides significant commission reduction.

Final Calculation (Line 17)

LOWER_DIVISOR + a as u32

The final denominator is the base (10) plus the number of 400-token tiers exceeded.

Why This Design?

The tier-based approach (every 400 tokens) creates a balanced system:

Gradual reduction: Commissions decrease smoothly, not in large jumps
Fair for all ranges: Small, medium, and large investors all benefit
Predictable: Easy to calculate and understand
Bounded: The cap prevents extreme edge cases

Real-World Examples

Investment	Formula	Calculation	Rate Denominator
50	N/A (≤100)	Base tier	10
100	N/A (=100)	Base tier	10
300	10 + (300-100)/400	10 + 0 (200/400 = 0)	10
500	10 + (500-100)/400	10 + 1 (400/400 = 1)	11
900	10 + (900-100)/400	10 + 2 (800/400 = 2)	12
1700	10 + (1700-100)/400	10 + 4 (1600/400 = 4)	14
5000	10 + (5000-100)/400	10 + 12 (4900/400 = 12)	22
25000	10 + (25000-100)/400	10 + 62 → capped	60

As smart contracts do not work with floating-point numbers, division is always integer-based. This is why (for instance) the 300 amount case results in the base tier denominator.

Practical example

For a 1400 USDC investment:

Unscale: 14000000000 / 10^7 = 1400 USDC
Excess over base limit: 1400 - 100 = 1300 USDC
400-token tiers: 1300 / 400 = 3 (integer based division)
Rate denominator: 10 + 3 = 13

Calculating the Final Commission

Once we have the rate denominator, the contract calculates the commission using this implementation:

let amount_to_commission = amount * (*i_rate as i128) / (rate_denominator as i128) / 100 / 100;

The two divisions by 100 are necessary because:

First division: Converts the rate denominator to a percentage
Second division: Converts the interest rate to a percentage (e.g., 850 → 8.5%) since it comes scaled as 10^2 to allow interests with decimals like (8.5%).

Complete Example: Project with 8.5% Yield

Imagine a project offering 8.5% yield (represented as 850 in the contract). Maria decides to invest 360 USDC tokens.

Step 1: Calculate the Rate Denominator

// Input: 3,600,000,000 (360 USDC tokens with 7 decimals)
let scale_factor = 10_i128.pow(7); // 10,000,000
let token_amount = 3_600_000_000 / 10_000_000; // 360 tokens

// Since 360 > 100:
let a = (360 - 100) / 400; // (260) / 400 = 0
let rate_denominator = 10 + 0; // 10

Step 2: Calculate the Commission

let i_rate = 850_u32; // 8.5%
let amount = 3_600_000_000_i128; // 360 scaled tokens

let amount_to_commission = (3_600_000_000 * 850) / 10 / 100 / 100;
// = 3_060_000_000_000 / 10 / 100 / 100
// = 306_000_000_000 / 100 / 100
// = 3_060_000_000 / 100
// = 30_600_000

// Unscaled: 30,600,000 / 10^7 = 3.06 tokens

Result

Project yield: 8.5%
Commission on investment: 0.85% (10 times lower than the yield)
Absolute commission: 3.06 tokens
Tokens available for yield generation: 356.94 tokens (after 0.85% commission)

Commission Comparison by Invested Amount

Let's see how commission varies for a project with 8.5% yield across different amounts:

Investment	Rate Denominator	Commission (USDC)	% Commission
50	10	0.43	0.85%
360	10	3.06	0.85%
1,000	12	7.08	0.71%
2,000	14	12.14	0.61%
5,000	22	19.32	0.39%
10,000	34	25.00	0.25%
50,000	60 (max)	70.83	0.14%

As you can see, the commission is inversely proportional to the amount invested, decreasing as the amount invested increases.

Conclusion

The dynamic commission system achieves a fair balance between sustainability and accessibility. By automatically adjusting rates based on investment size, we ensure that small investors have a fair entry point while rewarding larger commitments with better terms.

This approach, combined with transparent on-chain calculations and automatic token decimal handling, creates a commission structure that adapts to each investor's needs. The result is a system where everyone benefits: small investors keep more of their returns, large investors enjoy reduced costs, and the platform remains economically viable.

Handling Smart Contract Errors in Equillar. From Rust to PHP

Nacho Colomina Torregrosa — Sun, 09 Nov 2025 16:47:41 +0000

Introduction

When building decentralized applications that interact with smart contracts, one of the most critical aspects is proper error handling. In Equillar, a PHP/Symfony-based platform for learning and prototyping blockchain solutions, we demonstrate an error handling strategy that bridges the gap between Rust smart contracts and a PHP backend application.

In this article, I'll explain how to manage contract errors end-to-end, from definition in Rust to user-friendly messages in PHP applications.

What you'll learn: How to implement a robust error handling system between smart contracts and web applications.

The Challenge

Soroban smart contracts, written in Rust, need to communicate errors back to the calling application. These errors must be:

Well-defined and predictable
Easy to handle in the backend
Translatable to user-friendly messages

Let's analyze how we achieve this in Equillar.

Defining Errors in the Smart Contract

First, we define all possible errors in our Rust smart contract using an enum with the #[contracterror] attribute:

#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
#[repr(u32)]
#[contracterror]
pub enum Error {
    AddressInsufficientBalance = 1,
    ContractInsufficientBalance = 2,
    AmountLessOrEqualThan0 = 4,
    AddressHasNotInvested = 14,
    AddressInvestmentIsNotClaimableYet = 15,
    AddressInvestmentIsFinished = 16,
    AddressInvestmentNextTransferNotClaimableYet = 17,
    WithdrawalUnexpectedSignature = 21,
    WithdrawalExpiredSignature = 22,
    WithdrawalInvalidAmount = 23,
    ProjectBalanceInsufficientAmount = 24,
    ContractMustBePausedToRestartAgain = 25,
    ContractMustBeActiveToBePaused = 26,
    ContractMustBeActiveToInvest = 27,
    RecipientCannotReceivePayment = 28,
    InvalidPaymentData = 29
}

Each error variant has a unique numeric identifier. This is crucial because Soroban will use these numbers when reporting errors back to our application.

Throwing Errors from Contract Functions

In our contract code, we use a custom macro to make error handling more ergonomic. Here's how we define and use it:

macro_rules! require {
    ($cond:expr, $err:expr) => {
        if !$cond {
            return Err($err);
        }
    };
}

// Usage example
require!(tk.balance(&addr) >= amount, Error::AddressInsufficientBalance);

Understanding the Macro

For those new to Rust macros, let's break this down:

macro_rules! is Rust's declarative macro system. It allows us to define patterns that generate code at compile time.

Our require! macro:

Takes two arguments: a condition ($cond:expr) and an error ($err:expr)
Checks if the condition is false
If false, returns an error immediately
If true, execution continues

This pattern is similar to assertions in other languages but integrated into Rust's Result-based error handling. It makes our contract code cleaner and more readable:

// Instead of writing:
if tk.balance(&addr) < amount {
    return Err(Error::AddressInsufficientBalance);
}

// We can write:
require!(tk.balance(&addr) >= amount, Error::AddressInsufficientBalance);

Mirroring Errors in PHP

On the PHP side, we implement the same error structure using a PHP 8.1+ enum:

enum ContractError: int
{
    case AddressInsufficientBalance = 1;
    case ContractInsufficientBalance = 2;
    case AmountLessOrEqualThan0 = 4;
    case AddressHasNotInvested = 14;
    case AddressInvestmentIsNotClaimableYet = 15;
    case AddressInvestmentIsFinished = 16;
    case AddressInvestmentNextTransferNotClaimableYet = 17;
    case WithdrawalUnexpectedSignature = 21;
    case WithdrawalExpiredSignature = 22;
    case WithdrawalInvalidAmount = 23;
    case ProjectBalanceInsufficientAmount = 24;
    case ContractMustBePausedToRestartAgain = 25;
    case ContractMustBeActiveToBePaused = 26;
    case ContractMustBeActiveToInvest = 27;
    case RecipientCannotReceivePayments = 28;
    case InvalidPaymentData = 29;

    public function getMessage(): string
    {
        return match ($this) {
            self::AddressInsufficientBalance => 'Address has insufficient balance to perform this operation',
            self::ContractInsufficientBalance => 'Contract has insufficient balance to complete this transaction',
            self::AmountLessOrEqualThan0 => 'Amount must be greater than zero',
            self::AddressHasNotInvested => 'This address has not made any investment in the project',
            self::AddressInvestmentIsNotClaimableYet => 'Investment is not yet available to be claimed',
            self::AddressInvestmentIsFinished => 'Investment has finished and no more operations can be performed',
            self::AddressInvestmentNextTransferNotClaimableYet => 'Next investment transfer is not yet available to be claimed',
            self::WithdrawalUnexpectedSignature => 'Withdrawal signature is invalid or does not match the expected one',
            self::WithdrawalExpiredSignature => 'Withdrawal signature has expired and is no longer valid',
            self::WithdrawalInvalidAmount => 'Withdrawal amount is invalid',
            self::ProjectBalanceInsufficientAmount => 'Project does not have sufficient balance to perform this operation',
            self::ContractMustBePausedToRestartAgain => 'Contract must be paused in order to be restarted',
            self::ContractMustBeActiveToBePaused => 'Contract must be active in order to be paused',
            self::ContractMustBeActiveToInvest => 'Contract must be active to make investments',
            self::RecipientCannotReceivePayments => 'The recipient address cannot receive payments in the established contract asset',
            self::InvalidPaymentData => 'The payment data provided is invalid',
        };
    }
}

Key Points:

Identical numeric values: Each PHP enum case uses the same integer as its Rust counterpart
Human-readable messages: The getMessage() method provides user-friendly error descriptions

Extracting Contract Errors from Soroban Responses

When a Soroban contract throws an error, it returns a formatted string like:

HostError: Error(Contract, #14)

The number after the # is our error code. We need to parse this and map it to our enum. Here's how we do it:

/**
 * Extract and return a ContractError from a raw Soroban error string
 * Soroban returns contract errors in the format: "HostError: Error(Contract, #<error_code>)"
 */
public static function fromRawError(string $rawError): ?self
{
    if (preg_match('#Error\(Contract,\s*\#(\d+)\)#', $rawError, $matches)) {
        $errorCode = (int) $matches[1];
        return self::tryFrom($errorCode);
    }

    return null;
}

The regex pattern #Error$Contract,\s*\#(\d+)$# searches for an error text like "Error(Contract, #14)" in the error string and captures the number.

Putting It All Together

Finally, we use this in our exception handling when simulating transactions:

class SimulatedTransactionException extends \RuntimeException
{
    public function getError(): string
    {
        $contractError = $this->getContractError();
        return $contractError?->getMessage() ?? 'Unknown error';
    }

    private function getContractError(): ?ContractError
    {
        $rawError = match (true) {
            !empty($this->simulateTransactionResponse->resultError) 
                => $this->simulateTransactionResponse->resultError,
            $this->hasErrorMessage() 
                => $this->simulateTransactionResponse->getError()->message,
            $this->hasErrorData() 
                => json_encode($this->simulateTransactionResponse->getError()->data),
            default => null,
        };

        return is_null($rawError) ? null : ContractError::fromRawError($rawError);
    }

    private function hasErrorMessage(): bool
    {
        return $this->simulateTransactionResponse->getError() && $this->simulateTransactionResponse->getError()->message;
    }

    private function hasErrorData(): bool
    {
        return $this->simulateTransactionResponse->getError() && $this->simulateTransactionResponse->getError()->data;
    }
}

The Flow

Here's what happens when a contract error occurs:

Smart contract validates a condition using the require! macro
If validation fails, it returns Err(Error::AddressInsufficientBalance)
Soroban formats this as "HostError: Error(Contract, #1)"
PHP application receives this error during transaction simulation
Our exception handler uses regex to extract the error code (1)
ContractError enum maps code 1 to AddressInsufficientBalance
getMessage() returns the user-friendly message
Frontend displays: "Address has insufficient balance to perform this operation"

Benefits of This Approach

✅ Single Source of Truth: Error codes are defined once and mirrored exactly
✅ User-Friendly: Technical error codes become readable messages
✅ Maintainable: Adding new errors requires updating just two enums

Conclusion

Handling errors across different programming languages and runtime environments can be challenging, but with careful design, we can create a seamless experience. By mirroring our error definitions and using systematic parsing, Equillar ensures that contract errors are communicated clearly from the blockchain all the way to our users.

This pattern can be applied to any decentralized application that needs to bridge smart contract errors with backend application logic, regardless of the specific technologies involved.

If you want to analyze the code in more depth, you can visit the repository on GitHub.

How Equillar Uses PHP-Stellar SDK for Soroban Operations

Nacho Colomina Torregrosa — Mon, 20 Oct 2025 18:05:38 +0000

Introduction

Equillar is a PHP/Symfony-based fintech platform that serves as both an educational resource and a local development foundation for prototyping blockchain solutions. This article explores how Equillar uses PHP-Stellar SDK to perform blockchain operations, providing insights into integration patterns you can apply in your own projects.

What you'll learn: How to integrate PHP applications with Stellar blockchain, from key-pair generation to smart contract deployment and execution.

System Key Generation

When Equillar initializes for the first time, it needs to create what we call the "system wallet." This custodial wallet is fundamental for the companies platform's operations, as it acts as the digital identity that will deploy contracts, manage trustlines, and execute automatic administrative operations.

So far, all companies uses the same system wallet but it could be change in the future.

The platform operates with an interesting hybrid model: while users maintain full control of their own wallets for making investments, Equillar uses a custodial system wallet for all operations that require automation or are part of the companies operations.

System key generation is performed through the "GenerateSystemWalletCommand" command. The central part that uses PHP-Stellar SDK is the KeyPair generation and automatic testnet funding:

// In GenerateSystemWalletCommand.php
use Soneso\StellarSDK\Crypto\KeyPair;
use Soneso\StellarSDK\Util\FriendBot;

// Generate a new KeyPair if no secret key is provided
$keyPair = $secret ? KeyPair::fromSeed($secret) : KeyPair::random();

// On testnet, automatically fund the account
if ($blockchainNetwork->isTest()) {
    FriendBot::fundTestAccount($keyPair->getAccountId());
}

The need for a system wallet arises from several operational requirements. First, Soroban contracts need to be deployed by a specific account that acts as the "owner" of the code. Additionally, to operate with tokens like USDC and EURC, the platform must manage trustlines from its own account to these assets. Finally, many operations such as automated withdrawal processing or benefit distribution require the system to execute transactions autonomously.

Loading the System Wallet Account

To use the system wallet, Equillar implements the "StellarAccountLoader" service. The key elements that use PHP-Stellar SDK are:

// In StellarAccountLoader.php
use Soneso\StellarSDK\Crypto\KeyPair;
use Soneso\StellarSDK\Network;
use Soneso\StellarSDK\StellarSDK;

// Create KeyPair from decrypted private key
$this->keyPair = KeyPair::fromSeed($decryptedPrivateKey);

// Configure the network (testnet or mainnet)
$this->network = $systemWalletData->isTest ? Network::testnet() : Network::public();

// Create SDK instance and load current account data
$this->sdk = StellarSDK::getTestNetInstance();
$this->account = $this->sdk->requestAccount($this->keyPair->getAccountId());

The "requestAccount" method is fundamental because it queries the current state of the account on the Stellar network. It's not enough to have just the local KeyPair; we need to obtain updated information such as the current sequence number, available balances, existing trustlines, and other data that changes with each transaction. This information is essential for building valid transactions, as each transaction must include the correct sequence number of the account sending it.

Establishing Trustlines for Tokens

Once the system wallet is generated and operational, the next critical step is to establish the necessary trustlines. On the Stellar network, before being able to receive or handle any token other than native XLM, an account must explicitly "trust" that token by creating a trustline. This is a security mechanism that prevents unwanted tokens from appearing in an account.

For Equillar, which handles stablecoins like USDC and EURC, it's essential to establish these trustlines from the very beginning. Without them, the platform simply couldn't operate with these assets, which are fundamental for the investments it manages.

The "CreateSystemAddressTokenTrustlineCommand" command uses PHP-Stellar SDK to create and send the trustline:

// In CreateSystemAddressTokenTrustlineCommand.php
use Soneso\StellarSDK\AssetTypeCreditAlphanum4;
use Soneso\StellarSDK\ChangeTrustOperationBuilder;
use Soneso\StellarSDK\TransactionBuilder;

// Create the Stellar asset
$stellarAsset = new AssetTypeCreditAlphanum4($token->getCode(), $token->getIssuerAddress());

// Build the trustline operation
$cto = (new ChangeTrustOperationBuilder($stellarAsset))->build();

// Create, sign and send the transaction
$transaction = (new TransactionBuilder($this->stellarAccountLoader->getAccount()))
    ->addOperation($cto)->build();
$transaction->sign($this->stellarAccountLoader->getKeyPair(), $this->stellarAccountLoader->getNetwork());

$transactionResponse = $this->stellarAccountLoader->getSdk()->submitTransaction($transaction);

During Equillar's initial setup, this process is completely automated through specific CLI commands that execute the creation of trustlines for the main tokens the platform will handle:

# Create trustlines for main tokens
php bin/console app:system-address:create-token-trustline --token="USDC"
php bin/console app:system-address:create-token-trustline --token="EURC"

Deploying Smart Contract Code

With the system wallet configured and trustlines established, we arrive at one of the most important operations: deploying the contract code. This process is fundamental because it generates the WASM ID (Web Assembly ID), which is essentially the "template" that will be used later to create multiple contract instances.

It's important to understand that in Soroban, code deployment and contract instance creation are two separate operations. First, the compiled code (.wasm file) is uploaded to the network, which generates a unique identifier (WASM ID). Then, each time a new contract is needed, a specific instance can be created using that WASM ID as a base.

The Deployment Process in Detail

The "DeployContractService" service orchestrates the process, but the direct interaction with PHP-Stellar SDK occurs in the deployment operation:

// In DeployContractService.php - relevant part
$wasmContent = (new Filesystem())->readFile($wasmFile);
$wasmId = $this->deployContractOperation->deploy($wasmContent);

Building the Deployment Operation

The "DeployContractOperation" class coordinates the process and extracts the WASM ID from Soroban's response:

// In DeployContractOperation.php
public function deploy(string $wasmCode): string
{
    $operation = $this->deployWasmOperationBuilder->build($wasmCode);
    $transactionResponse = $this->processTransactionService->sendTransaction($operation);

    return $transactionResponse->getWasmId(); // PHP-Stellar SDK method
}

Building the WASM Operation

The "DeployWasmOperationBuilder" builder uses Soroban-specific SDK classes:

// In DeployWasmOperationBuilder.php
use Soneso\StellarSDK\InvokeHostFunctionOperationBuilder;
use Soneso\StellarSDK\UploadContractWasmHostFunction;

$uploadContractHostFunction = new UploadContractWasmHostFunction($wasmCode);
$builder = new InvokeHostFunctionOperationBuilder($uploadContractHostFunction);

return $builder->build();

Automation Through CLI Command

The "GenerateContractCommand" command simplifies the entire process for administrators:

// In GenerateContractCommand.php
$wasmId = $this->deployContractService->deployContract(
    $this->wasmFile, // Configured path to .wasm file
    $status,
    $vers,
    $comments
);

$io->writeln("✅ Contract deployed successfully");
$io->writeln("📋 WASM ID: {$wasmId}");

In the platform's initial configuration, this command is executed as part of the automated setup process, generating the WASM ID that will be the base for all investment contracts created subsequently:

# Deploy contract and get WASM ID
php bin/console app:contract:deploy --vers="1.0" --status=STABLE --comments="Main investment contract"

The Transaction Processing Engine

Behind all these operations we've seen - from trustline creation to contract deployment - there exists a central component that orchestrates the entire process: the "ProcessTransactionService". This service is the heart of Soroban integration and handles the complete flow required by smart contract transactions.

Soroban transactions require a multi-step process that "ProcessTransactionService" handles using PHP-Stellar SDK extensively:

// In ProcessTransactionService.php - key SDK elements
use Soneso\StellarSDK\TransactionBuilder;
use Soneso\StellarSDK\Soroban\Requests\SimulateTransactionRequest;

// Build the transaction
$transaction = (new TransactionBuilder($this->stellarAccountLoader->getAccount()))
    ->addOperation($operation)->build();

// Simulate to get necessary resources
$request = new SimulateTransactionRequest($transaction);
$simulateResponse = $this->server->simulateTransaction($request);

// Apply Soroban data to the transaction
$transaction->setSorobanTransactionData($simulateResponse->transactionData);
$transaction->addResourceFee($simulateResponse->minResourceFee);

// Sign with Stellar KeyPair and Network
$transaction->sign($keyPair, $network);

// Send and get response
$sendTransactionResponse = $this->server->sendTransaction($transaction);

// Wait for transaction confirmation
return $this->waitForTransaction($sendTransactionResponse->hash);

Waiting for Transaction Confirmation

Once the transaction is successfully sent to the Soroban network, it doesn't mean it's immediately confirmed. Soroban transactions are asynchronous and can take a few seconds to be processed and confirmed by the network. This is where the waitForTransaction method comes in, which is crucial for ensuring the operation completes correctly.

// In ProcessTransactionService.php - waitForTransaction method
public function waitForTransaction(string $hash, int $maxIterations = self::MAX_ITERATIONS): GetTransactionResponse
{
    $counter = 0;
    do {
        sleep(self::DEFAULT_WAITING_SLEEP); // Wait 1 second between queries

        $transactionResponse = $this->server->getTransaction($hash);
        $status = $transactionResponse->status;
        ++$counter;

    } while ($counter < $maxIterations && 
             !in_array($status, [GetTransactionResponse::STATUS_SUCCESS, GetTransactionResponse::STATUS_FAILED]));

    if (GetTransactionResponse::STATUS_SUCCESS !== $status) {
        throw new GetTransactionException($transactionResponse);
    }

    return $transactionResponse;
}

This method implements a polling pattern that periodically queries the transaction status using the hash returned by Soroban. Equillar configures a maximum of 10 iterations with 1-second intervals, meaning it will wait up to 10 seconds for the transaction to be confirmed. If the transaction fails or doesn't confirm within that time, it throws a specific exception that allows appropriate error handling.

Activating Individual Contracts

Once we have the deployed WASM ID, we can create specific contract instances. In Equillar, each investment project needs its own individual contract with unique parameters such as funding goal, return rate, deadlines, etc.

Individual contract activation is the process where the WASM ID (the template) is taken and a specific instance is created with the project's parameters. This process uses PHP-Stellar SDK to handle the complexity of constructor arguments.

The "ContractActivationService" service coordinates the entire process, but the specific blockchain operation occurs in "ContractActivationOperation":

// In ContractActivationOperation.php
public function activateContract(Contract $contract): GetTransactionResponse
{
    $lastDeployedContractCode = $this->contractCodeStorage->getLastdeployedContractCode();
    $operation = $this->contractActivationOperationBuilder->build($contract, $lastDeployedContractCode->getWasmId());

    return $this->processTransactionService->sendTransaction($operation, true);
}

Building Constructor Arguments

The most complex part of activation is building the constructor arguments. Equillar uses "ContractActivationOperationBuilder" to convert project data into the specific types that Soroban requires:

// In ContractActivationOperationBuilder.php
use Soneso\StellarSDK\CreateContractWithConstructorHostFunction;
use Soneso\StellarSDK\Soroban\Address;
use Soneso\StellarSDK\Xdr\XdrSCVal;

// Convert project data to Soroban types
$goalI128 = $this->tokenNormalizer->normalizeTokenValue($contract->getGoal(), $decimals);
$minPerInvestmentI128 = $this->tokenNormalizer->normalizeTokenValue($contract->getMinPerInvestment(), $decimals);

$constructorArgs = [
    Address::fromAccountId($systemAccount)->toXdrSCVal(),              // Administrator
    Address::fromAccountId($contract->getProjectAddress())->toXdrSCVal(), // Project
    Address::fromContractId($contract->getToken()->getAddress())->toXdrSCVal(), // Token
    XdrSCVal::forU32($rate),                                          // Return rate
    XdrSCVal::forU64($days),                                          // Days to claim
    XdrSCVal::forI128Parts($goalI128->getLo(), $goalI128->getHi()),   // Funding goal
    // ... more arguments
];

// Create the activation function with constructor
$createContractHostFunction = new CreateContractWithConstructorHostFunction(
    Address::fromAccountId($this->stellarAccountLoader->getAccount()->getAccountId()),
    $wasmId,
    $constructorArgs
);

What's fascinating here is how PHP-Stellar SDK handles the conversion from native PHP types to Soroban-specific types (XDR). For example, financial amounts are converted to 128-bit integers, addresses are transformed into specific "Address" objects, and simple numbers are wrapped in appropriate XDR types.

Contract Function Calls

Once contracts are active, Equillar can execute various operations by calling specific functions. Each contract function requires its own builder that handles specific parameters.

Example: Fund Withdrawal

A common operation is withdrawing funds from a contract. Let's see how Equillar uses PHP-Stellar SDK for this operation:

// In ContractWithdrawalOperationBuilder.php
use Soneso\StellarSDK\InvokeContractHostFunction;
use Soneso\StellarSDK\Xdr\XdrSCVal;

public function build(Contract $contract, float $amount): InvokeHostFunctionOperation
{
    // Normalize the amount to Soroban I128 format
    $amountI128 = $this->tokenNormalizer->normalizeTokenValue($amount, $contract->getToken()->getDecimals());

    // Create the contract function call
    $invokeContractHostFunction = new InvokeContractHostFunction(
        $contract->getAddress(),                    // Contract address
        ContractFunctions::single_withdrawn->name,  // Function name
        [XdrSCVal::forI128Parts($amountI128->getHi(), $amountI128->getLo())] // Arguments
    );

    $builder = new InvokeHostFunctionOperationBuilder($invokeContractHostFunction);
    return $builder->build();
}

Example: Balance Query

For read-only operations, such as querying a contract's balance, the pattern is similar but without arguments:

// In GetContractBalanceOperationBuilder.php
$invokeContractHostFunction = new InvokeContractHostFunction(
    $contract->getAddress(), 
    ContractFunctions::get_contract_balance->name  // No arguments for this function
);

$builder = new InvokeHostFunctionOperationBuilder($invokeContractHostFunction);
return $builder->build();

The Invocation Pattern

All contract function calls in Equillar follow a consistent pattern that PHP-Stellar SDK facilitates enormously:

Prepare arguments: Convert PHP data to XDR types using classes like "XdrSCVal"
Create InvokeContractHostFunction: Specify contract address, function name and arguments
Build operation: Use "InvokeHostFunctionOperationBuilder" to create the operation
Process transaction: Send through "ProcessTransactionService" that handles simulation, authorization and confirmation

This modular approach allows Equillar to add new functionalities simply by creating new builders for different contract operations, keeping the complexity of Soroban integration encapsulated and reusable.

Conclusion

Throughout this complete journey, we have seen how Equillar uses PHP-Stellar SDK to manage the entire lifecycle of Soroban contracts, from initial configuration to daily operations.

We started with the fundamentals: generation of system custodial wallet keys and establishment of trustlines for the stablecoins the platform handles. These components form the foundation upon which all of Equillar's blockchain operations are built.

Then we explored the contract code deployment process, seeing how the WASM ID that acts as a master template is generated. This process, though complex, is greatly simplified thanks to the abstractions provided by PHP-Stellar SDK.

Finally, we delved into the most sophisticated operations: activating individual contracts with their specific parameters and executing function calls for operations like withdrawals and balance queries. Here we saw how PHP-Stellar SDK elegantly handles the conversion between native PHP types and the XDR types that Soroban requires.

Equillar: Open-Source Fintech Foundation for Blockchain Investment Platforms

Nacho Colomina Torregrosa — Sun, 05 Oct 2025 12:46:07 +0000

Introduction

Lately, I've been fascinated by the intersection of blockchain technology, smart contracts, and the fintech world. The potential to create transparent, efficient, and accessible financial systems using decentralized technologies has captured my imagination.

As a developer who's spent considerable time working with PHP and Symfony, I found myself constantly thinking: "What if I could combine the reliability and developer experience of these mature technologies with the innovation of blockchain?"

That question led me to dive deeper into Stellar and Soroban smart contracts technologies I had already been exploring and working with for some time. Having developed several smart contracts on the platform, I was consistently impressed by Soroban's approach to making blockchain development more accessible while maintaining enterprise-grade security and performance.

Finally, I decided to channel this knowledge into something concrete: Equillar, an open-source platform designed to help developers learn blockchain development through a complete working example, or as a local development foundation for prototyping fintech solutions.

What is Equillar?

Equillar is a PHP/Symfony-based fintech platform that serves dual purposes: as a learning resource for blockchain development, and as a local development foundation that organizations can use for prototyping. It demonstrates how to build blockchain-powered applications through a practical investment platform example built with Soroban.

What Equillar Offers for Learning

Complete Application Stack

Backend API: Full Symfony application demonstrating authentication, user management, and blockchain contract interaction
Frontend Interface: React/TypeScript dashboard with Material UI components showing modern DApp patterns
Smart Contracts: Soroban contracts demonstrating automated investment management logic
Database Schema: PostgreSQL schema showing off-chain data management in blockchain apps

Development Infrastructure

Docker Environment: Easy local development setup with docker.
CI/CD Pipeline: GitHub Actions workflow with automated testing
Code Quality: PHPStan static analysis and test suite
Documentation: Detailed guides for setup, development, stellar wallet installation and how to use the dashboard.

Key Features Implementation

Multi-role System: Companies, investors, and administrators with different permissions.
Investment Workflows: Project creation, funding, and automated return distributions.
Blockchain Integration: Wallet connectivity and smart contract interactions.
Financial Calculations: Interest calculations, payment schedules, and balance management.

Technology Stack

Backend

PHP 8.3 with Symfony 7.3
PostgreSQL database
Contracts deployed on Soroban and written in the Rust language

Frontend

React 18
Typescript
Material (MUI): For the user interface

Backend / Frontend integration

Symfony UX together with webpack encore

Who Can Learn from Equillar?

Developers looking to understand blockchain integration can study Equillar's implementation of Stellar/Soroban connectivity
Students and universities can use Equillar as a teaching tool for blockchain development and fintech application patterns
Backend developers familiar with PHP/Symfony can learn how to integrate blockchain without switching technology stacks
Frontend developers can explore wallet integration and transaction handling in React applications
Blockchain enthusiasts can study a complete real-world use case beyond simple token transfers

Getting Started

Ready to start learning? Visit the documentation and GitHub repository to begin exploring.

A Symfony - React SPA application. The Reload problem

Nacho Colomina Torregrosa — Sat, 15 Feb 2025 10:11:22 +0000

Introduction

In this article, I would like to share with you a problem I encountered while developing a SPA in React within a Symfony project and how I resolved it.

The Context

I'm working on a Symfony based application which uses Symfony UX to integrate a React-SPA frontend within the Symfony application. The React frontend is loaded using a symfony controller which renders a twig file which renders the main react component:

#[Route('/app', name: 'get_app', methods: ['GET'])]
public function getApp(): Response 
{
    return $this->render('App.html.twig');
}

The twig file simply renders the main react component which loads the react SPA.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
        <meta name="description" content="" />
        <meta name="author" content="" />
        <title>{% block title %}Welcome!{% endblock %}</title>
        {% block stylesheets %}
            {{ encore_entry_link_tags('app') }}
        {% endblock %}
        {% block javascripts %}
            {{ encore_entry_script_tags('app') }}
        {% endblock %}
    </head>
    <body>
        <div {{ react_component('App') }} ></div>
    </body>
</html>

The react main AppComponent looks like this:

export default function App() {

    const wallet: Wallet = useStellarWallet(WalletNetwork.TESTNET);

    return (
      <Fragment>
        <CssBaseline />
        <WalletContext.Provider value={wallet}>
          <Router>
            <Routes>
              <Route path="/login" element={<SignIn />} />
              <Route path="/app" element={<ProtectedRoute children={<Layout /> } /> } >
                  <Route element={<Home />} />
                  <Route path="home-investor" element={<HomeInvestor />} />
                  <Route path="blogs" element={<Blogs />} />
                  <Route path="create-project" element={<CreateInvestmentProject />} />
                  <Route path="project/:id/start" element={<StartInvestmentProject />} />
                  <Route path="project/:id/invest" element={<SendInvestmentDeposit />} />
              </Route>
            </Routes>
          </Router>
        </WalletContext.Provider>
    </Fragment>
  );
}

As you can see, it uses the React Router component to define the routes tree.

The Problem

I use the react-router to manage the react SPA navigation within the useNavigate hook. This is an efficient way to navigate between routes and it works like a charm.
The problem is that, as I'm integrating react within a Symfony application, if I reload the application (on the browser), I get a Symfony error which tells me that such route does not exist. This is normal since the routes are defined in react, not in Symfony so the Symfony router cannot find them.

A partial solution

The first thing to do I thought about was to allow an slug on the "get_app" controller so that it would look like this:

#[Route('/app', name: 'get_app', methods: ['GET'])]
#[Route('/app/{slug}', name: 'get_app_with_slug', methods: ['GET'])]
public function getApp(): Response 
{
    return $this->render('App.html.twig');
}

This works when the slug value is a simply string like this:

https://127.0.0.1:8000/app/home-investor

But the symfony router will throw an error if the slug part contains a route with extra segments:

https://127.0.0.1:8000/app/project/2/invest

This is because the route "/app/{slug}" only captures a single segment after "/app/". This means that any URL with more than one segment after "/app/" will not match this route. For example, in the URL "https://127.0.0.1:8000/app/project/2/invest", there are three segments after "/app/" (project, 2, invest), which causes it not to match the route definition.

The Solution

The solution I finally chose involved a series of changes both in the backend part (Symfony) and in the frontend part (react). Let's start with the Symfony part.

Changes on the Symfony part

The first change of the symfony part was to create a Kernel Subscriber to catch the incoming request using the Symfony
KernelEvents::REQUEST event. Let's see the code:

public static function getSubscribedEvents(): array
{
    return [
        KernelEvents::REQUEST   => 'onRequest'
    ];
}

public function onRequest(RequestEvent $event): void
{
   $request = $event->getRequest();
   if (preg_match('#^\/app\/#', $request->getRequestUri())) {
       $pathSlug  = preg_replace('#^\/app\/#', '', $request->getRequestUri());
       $url = $this->router->generate('get_app', ['qslug' => $pathSlug]);
       $event->setResponse(new RedirectResponse($url));
   }
}

The onRequest function gets the Symfony Request object and extracts the "react route path" from the request uri. Then, it generates the "get_app" route passing it a parameter named "qslug" with the react route path value.
Finally, it sets the new response to the event as a Symfony RedirectResponse.

The second change involves modifying the "get_app" controller so that it passes the react route path to the App.html.twig file.

#[Route('/app', name: 'get_app', methods: ['GET'])]
public function getApp(#[MapQueryParameter] ?string $qslug): Response 
{
    return $this->render('App.html.twig', ['pathSlug' => $qSlug]);
}

Finally, The twig file also has to pass the slug to the react app component.

<!DOCTYPE html>
<html>
    <!-- Head -->
    <body>
        <div {{ react_component('App', {pathSlug: pathSlug}) }} ></div>
    </body>
</html>

Changes on the React part

Now in the react part, I needed to check whether this path had a value and, if so, navigate to it.

First of all, I created a hook named "useReloadedRoute":

export const useReloadedRoute = (path?: string) => {
    if(path){
        localStorage.setItem('route_to_redirect', path);
    }

    const getRouteToNavigate = () => {
        return localStorage.getItem('route_to_redirect');
    }

    const removeRouteToNavigate = () => {
        localStorage.removeItem('route_to_redirect');
    }

    return {
        getRouteToNavigate,
        removeRouteToNavigate
    };
}

The hook saves the path in the localStorage and provides a function to get the path to redirect and another one to remove it.

Then, I created a react context within the AppComponent to provide the reloaded route.

export const ReloadRouteContext = createContext<ReloadedRoute>(null);

interface AppProps {
  pathSlug?: string
}

export default function App(props: AppProps) {

    const wallet: Wallet = useStellarWallet(WalletNetwork.TESTNET);
    const reloadedRoute: ReloadedRoute = useReloadedRoute(props?.pathSlug);

    return (
      <Fragment>
        <CssBaseline />
          <ReloadRouteContext.Provider value={reloadedRoute} >
          <WalletContext.Provider value={wallet}>
            <Router>
              <Routes>
                <Route path="/login" element={<SignIn />} />
                <Route path="/app" element={<ProtectedRoute children={<Layout /> } /> } >
                    <Route element={<Home />} />
                    <Route path="home-investor" element={<HomeInvestor />} />
                    <Route path="blogs" element={<Blogs />} />
                    <Route path="create-project" element={<CreateInvestmentProject />} />
                    <Route path="project/:id/start" element={<StartInvestmentProject />} />
                    <Route path="project/:id/invest" element={<SendInvestmentDeposit />} />
                </Route>
              </Routes>
            </Router>
          </WalletContext.Provider>
          </ReloadRouteContext.Provider>
      </Fragment>
    );
}

Thanks to the ReloadRouteContext, I was ready to check for the path to redirect in the LayoutComponent.

const reloadedRoute: ReloadedRoute = useContext(ReloadRouteContext);

useEffect(() => {
   const rlRoute = reloadedRoute.getRouteToNavigate();
   if (rlRoute) {
       const path = '/app/' +rlRoute;
       reloadedRoute.removeRouteToNavigate();
       navigate(path);
   }
}, []);

Now, if there is a route to redirect stored, the LayoutComponent will remove it from the storage and navigate to it.

Conclusion

This is the way I resolved this issue. I hope that if you've experienced the same problem this solution can help you. Of course, if you know a better way to achieve that, please let me know in the comments so I can test it :).

If you like my content and it provides value to you, consider reading my book: Practical PHP APIs with Symfony