Core v2 integration
Deposit, issue PT and YT, claim yield, and redeem on Stellar Core v2.
The Principal Token is the main Core integration surface. It accepts underlying assets or IBT shares, issues equal PT and YT quantities, accounts for yield, and redeems the backing position.
Market initialization
A PT market requires:
- A non-empty IBT implementing the expected FungibleVault interface.
- An underlying token with at least six decimals.
underlying decimals <= IBT decimals <= 18.- A positive maturity duration.
Initialization records the live IBT conversion rate, sets the PT rate to one in 27-decimal Ray precision, calculates the expiry, and deploys the paired YT.
Deposit paths
| Entry point | Input | Result |
|---|---|---|
deposit | Underlying token | PT wraps the underlying into IBT, then issues PT and YT. |
deposit_ibt | IBT shares | PT receives the IBT directly, then issues PT and YT. |
The caller authenticates and grants the PT contract a SEP-41 allowance for the input. After the tokenization fee, shares are calculated as:
issued shares = floor(net IBT amount × IBT rate / PT rate)PT and YT can be sent to different receivers. The YT receiver's existing yield checkpoint is settled before minting.
Yield and rate updates
Per-user state stores the last observed IBT rate, PT rate, and accrued IBT yield. YT transfers and burns call back into PT so the affected holders are checkpointed before balances change.
If the IBT appreciates, the gain accrues to YT. If the IBT loses value, the shared PT rate can ratchet downward. Yield can be claimed as underlying or IBT after the current Registry yield fee is applied.
The yield fee is read when a claim executes. A governance fee change can therefore affect yield accrued before the change but not yet claimed.
Redemption
Before maturity, redemption settles yield and burns matching PT and YT. The maximum redeemable shares are bounded by both balances. Core converts PT shares back to IBT using:
IBT out = floor(PT shares × PT rate / IBT rate)redeem unwraps the IBT to underlying; redeem_for_ibt returns IBT. Exact-output withdrawals round the required PT shares upward.
After maturity, deposits stop, PT and IBT rates freeze, YT reports no economic balance, and PT can be redeemed without burning YT. A delegated pre-maturity redemption needs allowances for both the owner's PT and YT; administrator status does not bypass them.
Integration safeguards
- Apply token-decimal-aware slippage limits and expect floor or ceiling rounding.
- Verify the market against a curated allowlist rather than trusting Registry membership alone.
- Plan TTL maintenance for long-held, inactive positions.