> 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/end-to-end-transaction-flow.md).
# End to End Transaction Flow
A complete StoxFi transaction moves through three phases.
1. Shield
2. Confidential transfer
3. Unshield
The underlying asset begins on Robinhood Chain, remains locked there while confidential activity takes place on Ethereum, and is released back on Robinhood Chain after redemption.
### Transaction Flow
**StoxFi End to End Transaction Flow**
The complete flow moves from the user's public tokenized stock into StoxVault, through confidential settlement on Ethereum, and back to the underlying token following redemption.
### Phase 1: Shield
Shielding creates the confidential representation of an underlying token.
#### Step 1: User Holds the Underlying Token
The user begins with a standard 18 decimal ERC 20 on Robinhood Chain.
At this stage, the user's balance is public.
#### Step 2: Vault Approval
The user grants StoxVault an ordinary ERC 20 allowance for the amount to be deposited.
The approval uses:
`ERC20.approve(StoxVault, amount)`
#### Step 3: Deposit
The user calls:
`StoxVault.deposit(stock, amount, recipient, payFeesInLink, gasLimit)`
A verified StoxFi transaction deposited:
`2000 × 10^18`
The recipient was the depositing address, the CCIP fee was paid using the native token, and the gas limit was `1,500,000`.
#### Step 4: Custody and Decimal Conversion
StoxVault receives the underlying tokens.
The vault verifies that the expected quantity actually arrived by checking the change in its token balance. This rejects tokens that reduce the transferred quantity through a transfer fee.
The deposited amount is then converted from 18 decimals to the 6 decimals used by ConfidentialStock.
The conversion rate is:
`10^(18 − 6) = 10^12`
In the verified transaction:
`2,000 tokens = 2,000,000,000 confidential units`
Any remainder below one confidential unit is returned during the same transaction.
The accepted underlying amount is added to `lockedOf[stock]`.
#### Step 5: Supply Limit
Before the confidential representation is created, StoxVault checks that the resulting supply remains within the `uint64` range used by the confidential balance system.
The maximum confidential value is:
`2^64 − 1`
This prevents confidential addition from wrapping.
#### Step 6: Mint Instruction
StoxVault dispatches the mint instruction through CCIP.
The message contains:
`recipient`
and
`uint64 amount`
The amount inside this message is cleartext.
The vault emits the `Deposited` event containing the corresponding CCIP message identifier.
#### Step 7: Message Delivery
The cross chain message is delivered to ConfidentialStock on Ethereum.
The receiving contract validates the message before processing it.
It verifies the source chain and sender and checks whether the message identifier has already been processed.
Replay of the same message therefore cannot create the confidential balance twice.
#### Step 8: Confidential Balance Creation
After validation, ConfidentialStock converts the public amount into an encrypted `euint64`.
The amount is added to the recipient's encrypted balance.
Access rights are then granted to the contract and the recipient.
ConfidentialStock emits `ConfidentialMint`.
#### Shield Visibility
The shield amount is public.
The exact ERC 20 deposit is visible on Robinhood Chain, and the amount is transmitted in cleartext through the mint instruction.
**Confidentiality does not begin at shield.**
It begins when the resulting confidential position is transferred using an encrypted amount.
### Phase 2: Confidential Transfer
Confidential transfers take place on Ethereum.
No cross chain message is required for a transfer between confidential balances.
#### Step 9: Amount Encryption
The transfer amount is encrypted in the browser before it is submitted to ConfidentialStock.
The encryption process produces an encrypted input together with a proof bound to the contract and sender.
This prevents the encrypted input from being submitted by another account or reused against another contract.
#### Step 10: Transfer on Encrypted Values
The encrypted amount is submitted to `confidentialTransfer`.
ConfidentialStock validates the encrypted input and performs the transfer without decrypting the amount.
The amount remains encrypted throughout the operation.
#### Step 11: Confidential Settlement
StoxFi evaluates two conditions on encrypted values.
First, whether the sender has sufficient funds.
Second, whether the recipient has sufficient balance capacity.
The contract then selects either the requested encrypted amount or encrypted zero.
If the conditions are satisfied, the requested value moves.
If they are not satisfied, zero moves.
The transaction can therefore complete without revealing the sender's balance through a revert.
The sender's encrypted balance is debited and the recipient's encrypted balance is credited.
#### Step 12: Updated Access Rights
After the transfer, access rights are granted for the updated balances.
The transferred value is made accessible to both the sender and recipient.
The contract emits:
`ConfidentialTransfer(from, to)`
The event contains the two participant addresses.
It contains **no transfer amount**.
### Phase 3: Unshield
Unshielding converts a confidential position back into the underlying ERC 20 held in StoxVault.
#### Step 13: Redemption Request
The holder submits a redemption request containing a destination and an encrypted amount.
The requested amount is limited to the holder's available encrypted balance.
The resulting amount is burned immediately and assigned to a redemption request identifier.
The burn occurs before the collateral release process.
This prevents the same confidential balance from being spent while redemption is pending.
It also allows the redemption process to be resumed later.
#### Step 14: Public Decryption Request
The burned encrypted amount is marked as publicly decryptable.
This transition is necessary because StoxVault must ultimately release an exact public quantity of the underlying ERC 20.
The contract emits `RedeemRequested`.
#### Step 15: Threshold Decryption
The browser requests public decryption through the FHE relayer.
The process returns the clear amount together with the signatures required for verification.
The verified StoxFi redemption transaction carried a `914` byte proof.
#### Step 16: Redemption Finalization
The redemption is finalized using:
`finalizeRedeem(requestId, clearAmount, decryptionProof, payFeesInLink, gasLimit)`
ConfidentialStock verifies that the supplied proof corresponds to the encrypted amount associated with the redemption request.
Finalization is permissionless.
Another account can finalize a pending redemption, but it cannot change the destination because the destination was fixed when the redemption request was created.
#### Step 17: Release Instruction
After successful verification, ConfidentialStock dispatches a release instruction through CCIP.
The message contains:
`destination`
and
`amount`
The contract emits `RedeemFinalized`.
#### Step 18: Collateral Release
StoxVault receives the release instruction on Robinhood Chain.
Before releasing collateral, the vault validates the source chain and peer and checks whether the message has already been processed.
The release is also capped by the amount recorded in `lockedOf[stock]`.
The corresponding ERC 20 amount is then transferred to the redemption destination.
StoxVault emits `Released`.
#### Step 19: Final State
Following redemption, the underlying token has returned to the designated destination on Robinhood Chain.
The public collateral relationship is:
`lockedOf[stock] = live confidential supply × rate`
The holder can also read the handle for their remaining encrypted balance and decrypt it through a request scoped to their address.
### Visibility Across the Lifecycle
| Stage | Amount Visibility | Balance Visibility | Participants |
| --------------------- | ----------------- | --------------------------- | ------------ |
| Shield | Public | Public before deposit | Public |
| Confidential transfer | Encrypted | Encrypted | Public |
| Unshield | Public | Remaining balance encrypted | Public |
The confidentiality boundary therefore exists during the confidential settlement interval.
Shield amounts are public.
Transfer amounts are encrypted.
Unshield amounts are public.
### Demonstrated Lifecycle
The StoxFi testnet implementation has demonstrated this complete sequence using live transactions across Robinhood Chain testnet and Ethereum Sepolia.
The demonstrated lifecycle included a shield of `2,000` tokens, a confidential transfer on Ethereum, and subsequent redemptions.
The confidential transfer transaction emitted the sender and recipient without an amount field, while the redemption process successfully returned underlying collateral through the reverse cross chain flow.
---
# 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/end-to-end-transaction-flow.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.
