Coupon Auto-Reinvestment
Coupons reach the vault through the same onchain distribution path as wallet holders, the vault address is included in the entitlement snapshot and the relayer claims on its behalf. See Coupon Distribution for the full registration, snapshot, Merkle tree building, and claim sequence. Once stablecoin arrives in the vault, a relayer-triggered swap converts it to Bond Tokens and completes the reinvestment.
Compounding Efficiency vs. Traditional Markets
In traditional bond markets, the minimum tradable lot is typically $200,000 face value. For a semi-annual 10% bond, a holder would need at least $4,000,000 in Bond Token face value to reinvest a single coupon payment back into that same bond at the minimum $200,000 lot. Bond Tokens lower the holding threshold to any fraction (but reinvesting coupon stablecoin for Bond Tokens still requires accessing a liquid market. The Reinvestment Vault handles this by pooling all vault holders' coupon proceeds into a DEX swap. In practice this delivers institutional-grade compounding access to holders at any position size) a theoretical efficiency improvement of up to four million times compared to the traditional minimum lot constraint.
Bondi works with liquidity providers to ensure the Bond Token pool can absorb coupon reinvestments at minimal slippage. A pending reinvestment state is transient (coupon proceeds are expected to be swapped into Bond Tokens promptly, normally for the full pending amount in a single call. If a swap call fails) oracle staleness, pool deviation exceeding the oracle threshold, or execution output falling below the quoter-derived floor, the call reverts and proceeds remain in pendingReinvestment. Exit treatment for pending proceeds follows Compliance at Reinvestment Vault Exit.
Coupon Reinvestment Flow
Steps 1–5 (gross transfer through Merkle finalization) are identical to Coupon Distribution. Furthermore, this diagram shows the Reinvestment Vault-specific steps after the standard coupon distribution path.
How Coupon Reinvestment Works
1. Gross coupon transfer through Merkle finalization
This step covers steps 1 to 5 above and follows the standard coupon distribution path, see Coupon Distribution. The snapshot and Merkle tree include the vault address as an ordinary holder.
2. Relayer coupon claim
The relayer calls Distribution.claimCouponForUser(vault, couponId, amount, proof) on behalf of the vault address. Because the Reinvestment Vault is a whitelisted Bondi vault, Distribution transfers stablecoins to the vault and immediately calls the vault's registerCoupon callback in the same transaction.
3. Pending state
Once registerCoupon is called on the vault, the pending reinvestment balance is active. The oracle share price immediately reflects the pending stablecoin value. New depositors pay a fair oracle-adjusted entry price that already prices in the pending coupon.
4. Swap: Coupon Proceeds → Bond Tokens
The admin or relayer calls reinvestCoupon(amount) on the vault. In normal operation this is always called for the entire pending coupon balance, the amount parameter gives the contract flexibility, but partial coupon swaps are not standard practice. The vault executes a Uniswap v3 swap: stablecoins in, Bond Tokens out. Three checks run before and during the swap:
- Freshness check: the oracle price (cbonds real-world price) must be less than 24 hours old. If stale, the call reverts.
- Oracle deviation check: the vault obtains a Uniswap quoter output for the exact trade size; the implied price is compared against the oracle price. If the deviation exceeds
oracleDeviationThreshold(default 2.5%), the call reverts. This check detects a pool that has moved far from the real-world reference price. - Quote-to-execution slippage check: the vault passes
amountOutMinimum = quoterOutput × (1 − slippageThreshold)to the Uniswap router. If actual execution delivers fewer Bond Tokens than that floor, the router call reverts. This check is anchored to the quoter output (not the oracle price) and catches sandwich attacks and thin-liquidity fills that occur between the quote and the actual execution.
If any check fails, the call reverts and the coupon remains in pendingReinvestment. There is no onchain cooldown (the admin or relayer can retry at any time) but operationally Bondi tries again as soon as conditions allow, and roughly once a day thereafter, until the swap clears.
On success, Bond Tokens are added to the vault and totalAssets() increases. The pending stablecoin clears; the oracle's stable component returns to zero and the BT component rises to reflect the new Bond Token balance. The net oracle price is approximately unchanged as the coupon value was already tracked in stablecoin form throughout the pending window.
If a second coupon arrives while a reinvestment is still pending, the two amounts are merged into the same pending bucket and reinvested together in the next successful swap.
Price Protection
Two independent guards protect shareholders from receiving fewer Bond Tokens than fair market value. The oracle deviation check detects when the pool price has moved far from the real-world cbonds price, a signal of pool manipulation or unusually thin liquidity. The quote-to-execution slippage check anchors the minimum acceptable swap output to the Uniswap quoter's result at the time of the call, catching sandwich attacks that occur between the quoter query and the actual fill. Both guards revert the call if triggered. There is no onchain cooldown, so the admin or relayer can retry at any time; in practice Bondi retries as soon as conditions allow and roughly once a day thereafter, until market conditions normalize and the swap clears.