> For the complete documentation index, see [llms.txt](https://stoxfi.gitbook.io/stoxfi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stoxfi.gitbook.io/stoxfi-docs/system-architecture.md). # System Architecture StoxFi operates across two blockchain environments connected through cross chain messaging and supported by external confidential computation infrastructure. The architecture consists of: 1. Robinhood Chain for underlying asset custody 2. Ethereum for confidential execution 3. Chainlink CCIP for cross chain instructions 4. The FHE infrastructure for encrypted computation and decryption 5. A browser application for direct user interaction StoxFi itself is built around three contracts: `StoxVault`, `ConfidentialStock`, and `StoxRegistry`. There is no StoxFi backend, API service, database, sequencer, or StoxFi operated relayer. The application communicates directly with blockchain RPC endpoints, the external FHE relayer, and the user's wallet. ### Architecture Overview The system separates custody, confidential execution, and cross chain communication. On Robinhood Chain, the underlying ERC 20 asset remains inside StoxVault. On Ethereum Sepolia, ConfidentialStock maintains the encrypted representation of the corresponding position. Chainlink CCIP carries instructions between the two environments. The FHE infrastructure provides encrypted computation, access control, and threshold decryption for the confidential balances maintained by ConfidentialStock. This separation allows the underlying collateral to remain on its original chain while confidential balance operations take place on Ethereum.
### Robinhood Chain The current StoxFi deployment uses Robinhood Chain testnet with chain ID `46630`. This environment contains the underlying ERC 20 assets, StoxVault, and the Chainlink CCIP Router used by the vault. #### Tokenized Stock ERC 20 The underlying asset is represented as a standard ERC 20 with 18 decimals in the current implementation. Its balance and transfer activity are public. During shielding, the user approves StoxVault and deposits the desired amount. The token remains inside StoxVault while the corresponding confidential representation exists. #### StoxVault StoxVault is the custody component of StoxFi. It is responsible for receiving the underlying ERC 20, verifying the exact amount received, converting between the underlying and confidential decimal representations, tracking locked collateral, sending mint instructions, receiving release instructions, and returning collateral following a valid redemption. For each supported asset, StoxVault maintains the amount of collateral currently locked. The vault also maintains the relationship between each supported stock and its corresponding ConfidentialStock contract. ### Ethereum Sepolia The current confidential execution environment is Ethereum Sepolia with chain ID `11155111`. This environment contains the ConfidentialStock contracts, StoxRegistry, and the Ethereum side of the CCIP connection. #### ConfidentialStock A ConfidentialStock contract represents the confidential version of a supported asset. Balances are maintained as encrypted `euint64` values with 6 decimals. ConfidentialStock performs encrypted balance operations, confidential transfers, minting following validated shield instructions, and the redemption process required to return a position to its underlying asset. Minting cannot be initiated by an administrator. It occurs only after a valid cross chain message is received from the bound StoxVault. Each ConfidentialStock is bound to its corresponding vault through a one time configuration. #### StoxRegistry StoxRegistry provides asset discovery on Ethereum. It holds no funds and has no authority over StoxVault or ConfidentialStock balances. Its role is limited to maintaining the asset listings used for discovery. Listings can be activated or deactivated without changing the underlying vault and confidential token relationship. ### Cross Chain Messaging StoxFi uses Chainlink CCIP to communicate between Robinhood Chain and Ethereum. CCIP is used for arbitrary messaging. The underlying ERC 20 is not transferred through CCIP. The `tokenAmounts` field remains empty. Instead, StoxFi sends instructions containing the information required to create or release the confidential representation. For shielding, the message contains the recipient and a `uint64` amount. For unshielding, the message contains the destination and a `uint64` amount. Each receiving contract validates the message before processing it. Validation includes: 1. Router validation 2. Source chain validation 3. Sender validation 4. Replay protection This prevents an arbitrary sender or previously processed message from authorizing minting or collateral release. ### Confidential Computation Infrastructure ConfidentialStock uses the FHE infrastructure available on Ethereum to operate on encrypted balances. The infrastructure includes: 1. An FHE coprocessor 2. An access control layer 3. A threshold KMS verifier 4. An external relayer The coprocessor supports the encrypted operations used by ConfidentialStock. The access control layer determines which accounts and contracts are permitted to use encrypted handles. The threshold decryption infrastructure is used during redemption when a burned encrypted amount must become publicly decryptable. The resulting clear value and signatures are then verified by ConfidentialStock before the release instruction can be sent. Nothing is decrypted directly onchain. ### Browser Application StoxFi includes a static browser application built with Vite, React 18, wagmi, Reown AppKit, and the FHE relayer SDK. The application provides interfaces for: 1. Shielding 2. Confidential transfers 3. Unshielding 4. Portfolio interaction The application communicates directly with the user's wallet, blockchain RPC endpoints, and the external FHE relayer. There is no StoxFi operated backend between the user and the contracts. Local browser storage can mirror pending operations for user experience purposes, but it does not determine protocol state. The authoritative state remains onchain. ### System Components | Component | Environment | Function | | ---------------------- | ----------------------- | ------------------------------------------------------------- | | Tokenized Stock ERC 20 | Robinhood Chain | Underlying public asset | | StoxVault | Robinhood Chain | Collateral custody, decimal conversion, release authorization | | CCIP Router | Robinhood Chain | Cross chain message routing | | ConfidentialStock | Ethereum Sepolia | Encrypted balances, confidential transfers, redemption | | StoxRegistry | Ethereum Sepolia | Asset discovery | | CCIP Router | Ethereum Sepolia | Cross chain message routing | | FHE Coprocessor | External infrastructure | Encrypted computation | | ACL | External infrastructure | Encrypted handle permissions | | Threshold KMS Verifier | External infrastructure | Redemption decryption verification | | Relayer | External infrastructure | Encryption and decryption interaction | | StoxFi Web Application | Browser | User interaction | ### Architectural Boundaries The architecture establishes clear responsibilities between its components. **StoxVault controls collateral.** It receives and releases the underlying ERC 20 and tracks the amount locked for each asset. **ConfidentialStock controls the confidential representation.** It maintains encrypted balances, performs confidential transfers, and manages redemption. **StoxRegistry provides discovery.** It does not custody assets or authorize value movement. **CCIP carries instructions.** It does not carry the underlying collateral. **The FHE layer performs confidential computation.** It enables ConfidentialStock to operate on encrypted values and provides the decryption process required for redemption. **The browser application provides user interaction.** It does not replace onchain state with an offchain database. This structure keeps the underlying collateral, confidential representation, messaging layer, and user interface as distinct components of the StoxFi system. ### Current Network Architecture The active StoxFi implementation is deployed entirely on test networks. | Network | Chain ID | StoxFi Role | | ----------------------- | ---------: | ------------------------ | | Robinhood Chain testnet | `46630` | Underlying asset custody | | Ethereum Sepolia | `11155111` | Confidential execution | No StoxFi contracts are currently deployed on Ethereum mainnet or Robinhood Chain mainnet. The current architecture has been used to demonstrate the complete shield, confidential transfer, redemption, and collateral release lifecycle across the two test networks. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://stoxfi.gitbook.io/stoxfi-docs/system-architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.