BWB × Stellar
Technical Integration Architecture
A concise architectural breakdown for integrating Stellar as a supported network within BWB's regulated tokenization platform, incorporating Soroban for asset lifecycles, and DeFindex for optional investor Yield rails.
1 Scope and Architectural Intent
BWB operates a regulated real estate tokenization platform orchestrating the entire lifecycle of tokenized offerings. This architectural program integrates Stellar as a primary network rail, unlocking low-cost multi-asset settlement and providing optional Soroban-native Yield products for investors.
The architecture relies on a provider-independent domain layer where external vendors sit behind strict abstraction boundaries. BWB's Convex backend orchestrates all compliance gates, transaction envelope preparation, and real-time state indexing into a unified portfolio dashboard, while Stellar acts as the immutable execution layer. Support for legacy EVM chains is maintained via secondary provider adapters.
Stellar and Soroban serve as the primary execution network for new regulated offerings and DeFi products.
Identity verification, investor accreditation, allocation caps, and regulatory disclosures precede on-chain transaction creation.
Personal data and identity documents remain strictly off-chain; contracts operate on state assertions and identifiers.
Every transaction state transition is event-indexed, reconciled with off-chain ledgers, and audited for operational integrity.
2 Target System Architecture
The architecture separates the client layer, server layer, off-chain data storage, and external network/partner integrations into clean, modular layers. The platform uses React for the web application user interface and Convex for backend web services, database storage, async event queues, and real-time state synchronization.
| Component | Role & Capabilities |
|---|---|
| Client Layer | Single-page web applications built with React for Investor Platform (portfolio, subscription, yield), Issuer workspace, Distributor workspace, and Operations dashboard. |
| Server Layer | Backend web services, reactive database store, event queues, and state orchestration powered by Convex. Manages policy enforcement, sequential eligibility gates, investment pipeline, attribution rules, webhooks, and transaction envelope generation. |
| Wallet Infrastructure | Non-custodial embedded key management and user-authorized transaction signing via Privy for Stellar accounts, with secondary support for EVM accounts. |
| Smart Contracts Layer | Soroban WASM smart contracts on Stellar enforcing offering lifecycle, asset minting, transfer restrictions, allocation limits, and event emissions. |
| KYC & Identity Providers | Identity verification and compliance gating. Avenia provides streamlined KYC/KYB tailored for unified network onboarding. |
| Fiat Ramp Providers & Bridge | BRL entry/exit services and cross-chain routing. Avenia and Circle CCTP provide a unified EVM PIX to Stellar USDC bridging pipeline. |
| DeFi Partner Integrations | Soroban DeFi protocols. DeFindex provides automated yield vault strategies (USDC Blend and TESOURO vaults). |
| Indexing & Network Services | Soroban RPC / Horizon node indexers capturing real-time block and ledger events to reconcile on-chain terminal states with off-chain Convex ledgers. |
3 End-to-End Investor Journeys
BWB supports two distinct investor onboarding and execution workflows: Individual Investors (Persons) and Organization Investors (Entities). While both require compliance verification before accessing primary offerings or DeFi product rails, Organization Investors undergo KYB verification and utilize a multi-signature approval layer for all financial transactions.
1. Individual Investor Journey (Person)
Individual investors complete Privy authentication and compliance verification to unlock direct PIX deposits, single-signature portfolio subscriptions, and DeFindex yield vaults.
2. Organization Investor Journey (Corporate Entity)
Corporate investors undergo KYB verification and enforce institutional governance through a **Multisig approval** threshold before submitting any XDR envelopes to Stellar.
4 Regulated Tokenization Rail
Regulated primary offerings on Stellar execute via Soroban smart contracts following off-chain compliance verification. Investor funding for these tokenized offers utilizes the unified cross-chain bridge pipeline, converting Base BRLA deposits to Stellar USDC via Avenia's internal FX and Circle CCTP. The sequence diagram below details how investor intent and identity gating trigger BWB's Convex backend to prepare unsigned XDR transaction envelopes, which are then passed to the user's Privy wallet for signature authorization and final execution before Convex indexes the resulting terminal states.
5 Yield Rail
Integrating Stellar enables an optional financial product rail for platform investors: automated Yield strategies via DeFindex (specifically enabling USDC Blend and TESOURO vaults). This rail operates independently on Soroban contracts, isolating DeFi strategy risks from regulated real estate tokenization income. BWB provides a unified onboarding route: existing BRL deposits route through the Avenia EVM (Base) pipeline as BRLA, which are then converted to USDC via Avenia's Internal FX API and bridged 1:1 to Stellar via Circle CCTP (@circle-fin/bridge-kit). This unified Swap & Bridge mechanism is the core funding pipeline for both Tokenized Offers and Yield. Vault positions and yield returns are indexed in real time into Convex for portfolio tracking.
6 Technical Integration & Partner Mapping
BWB's platform architecture encapsulates external protocols behind vendor-agnostic domain interfaces. The matrix below defines how Stellar ecosystem building blocks and partner integrations are mapped directly into BWB's regulated tokenization engine and Convex backend.
| Stellar & Partner Building Block | Technical Architecture & Capability | BWB Platform Integration Boundary |
|---|---|---|
| DeFindex Soroban Yield Engine (@defindex/sdk) | Programmatic Soroban yield aggregator deploying non-custodial vaults and auto-compounding strategies. |
Yield Product Rail: Convex backend consumes @defindex/sdk to construct unsigned XDR payloads (depositToVault, withdrawFromVault). BWB operates a platform USDC vault; Yield metrics and balances sync in real time.
|
| Circle CCTP (@circle-fin/bridge-kit) | Official Circle protocol enabling 1:1 permissionless burn-and-mint cross-chain transfer of native USDC between EVM (Base) and Stellar. |
Cross-Chain Bridge Gateway: Ingested via Bridge Kit SDK in Convex getCryptoSwapQuote pipeline; burns USDC on Base and mints native Stellar USDC directly into investor's Privy wallet.
|
| Privy Embedded Key Management (ed25519) | Non-custodial identity authentication and client-side ed25519 keypair management for native Stellar accounts. | Key Management Layer: Provisions non-custodial Stellar wallets for registered investors. Handles client-side user signature authorization for prepared XDR transaction envelopes without exposing private keys. |
| Protocol Reserve Sponsorship (CAP-33) & Trustlines | Native Stellar account sponsorship framework for minimum XLM account balances and asset trustline entries. | Account Provisioning: BWB platform treasury sponsors base XLM account reserves and asset trustlines (USDC, tokenized assets), enabling immediate self-custody without requiring end users to hold XLM. |
| Fee-Bump Transaction Relays | Dual-envelope transaction model wrapping an inner signed user payload within an outer fee-paying transaction envelope. | Gasless Execution Engine: BWB channel-account pool signs outer fee-bump envelopes to cover Stellar network fees, preventing transaction sequence collisions and delivering a zero-gas UX. |
| Soroban Regulated Offering Contracts (SEP-0041) | Rust/WASM smart contracts implementing SEP-0041 token standards with built-in transfer restrictions and compliance hooks. | Asset Lifecycle Layer: Enforces CVM 88 regulatory rules, primary offering cap tables, investor allocation limits, and distribution rules natively on Stellar. |
| Soroban RPC & Horizon Indexing Pipeline | High-availability ledger query, transaction submission, and event stream ingestion infrastructure. | State Reconciliation: Continuous event-listener polling Stellar ledger states, normalizing transaction receipts, and updating Convex reactive database ledgers with terminal transaction status. |
7 Bidirectional Base–Stellar settlement corridor
The v23 corridor combines Avenia's BRL/USDC conversion and Base settlement with Circle CCTP's native-USDC transport. It is a non-custodial workflow whose provider, chain, and accounting states are joined by one durable transfer identifier and an append-only reconciliation record.
| Stage | Forward: BRL/Base → Stellar | Reverse: Stellar → Base/BRL | Required evidence |
|---|---|---|---|
| 1. Quote and intent | Avenia quote/ticket and user funding intent. | User withdrawal intent and eligible BRL destination. | Quote version, expiry, user authorization, amount, asset, and destination. |
| 2. Source settlement | BRL conversion and native USDC available on Base. | User-authorized CCTP burn of native USDC on Stellar. | Avenia ticket, source transaction, normalized six-decimal USDC amount. |
| 3. CCTP transport | Base burn, Circle attestation, Stellar mint, then CctpForwarder delivery. | Stellar burn, Circle attestation, and Base mint. | Source domain, nonce, message hash, attestation, destination transaction. |
| 4. Terminal settlement | Final Stellar wallet balance available for an offering, vault, or lending market. | Base balance reconciled and, when requested, settled in BRL through Avenia. | Final balance, terminal status, timestamps, exceptions, and ledger postings. |
8 Security & Operational Model
The operational model applies defense-in-depth across identity, transaction validation, smart contracts, and network state monitoring.
Authorization & Access
Role-based access controls for operations, explicit wallet signature requirements for all on-chain actions, and strict API route authorization.
Data Minimization
Zero personal documents or raw identity data stored on-chain. Only boolean eligibility assertions and hashed references are passed to contracts.
Idempotent Execution
All webhooks, transaction submissions, and indexed event handlers use unique idempotency keys to prevent duplicate processing.
Transaction Integrity
Prepared transaction envelopes specify exact parameter limits, preventing parameter manipulation prior to user signing.
Circuit Breakers
Admin emergency pause controls on Soroban contracts to freeze primary sales or transfers in case of detected anomalies.
Real-Time Monitoring
Continuous monitoring of Soroban RPC / Horizon indexers, vault health factors, webhook processing latency, and ledger reconciliation gaps.
9 Delivery Mapping
Stellar integration is executed in three controlled phases to guarantee technical stability, compliance validation, and seamless user experience.
Stellar Wallet & Soroban MVP
Privy Stellar wallet integration, basic Soroban offering contracts, Soroban RPC / Horizon event indexer, and primary subscription workflow.
DeFi Rails & Cross-Chain Bridge
DeFindex yield vault adapter, Circle CCTP cross-chain bridging pipeline, bidirectional Base-Stellar corridor, and security threat modeling.
Mainnet & Hardening
Mainnet contract deployment, end-to-end reconciliation testing, monitoring activation, public documentation release, and feature-gated corridor readiness check.