PT bridge integration
Architecture and safety requirements for EVM–Stellar Principal Token transfers.
The bridge has independent EVM and Soroban deployments connected through messenger adapters. It supports both EVM-origin and Stellar-origin PTs.
Use the ABI and contract specification for the deployed versions. Core Router and bridge signatures must match before routed transfers can be submitted. See Deployed Contracts for infrastructure addresses by network.
Components
| Side | Components |
|---|---|
| EVM | PT bridge, wrapped Stellar PT implementation, Axelar adapter, LayerZero adapter, and message libraries. |
| Stellar | PT bridge, wrapped PT, shared bridge traits, and Axelar adapter. |
Axelar adapters are implemented on both sides. LayerZero is available as an EVM adapter only.
Transfer state machine
| Flow | Source | Destination |
|---|---|---|
| EVM-origin PT to Stellar | Collect gross PT, charge the source fee, and lock the net amount. | Resolve or deploy the mapped SEP-41 wrapper and mint the net amount. |
| Return to EVM | Charge the source fee and burn the Stellar wrapper. | Reduce locked backing and transfer the original PT. |
| Stellar-origin PT to EVM | Charge the source fee and lock the native PT. | Resolve or deploy the mapped ERC-20 wrapper and mint it. |
| Return to Stellar | Charge the source fee and burn the EVM wrapper. | Reduce locked backing and transfer the original Stellar PT. |
Inbound calls require the current or accepted previous messenger, a trusted remote for the source chain, an unpaused bridge, and a valid payload. Replay prevention and exactly-once delivery are delegated to the messenger protocol.
Fees, gas, and limits
- Fees are taken only on the source leg and reduce the bridged amount.
- Rate limits track directional per-token volume over a configured window.
- Cross-chain gas is separate from the bridge fee.
- A locally successful lock or burn can precede a failed or delayed destination call.
Direct bridge invocation and Core Router invocation can apply different safeguards. Bind your client to a release where the Router's argument and return types match the bridge, and enforce a user-selected minimum amount, maximum fee, gas floor, and refund address where the release supports them.
Client checklist
- Verify the source PT and its origin mapping.
- Validate EVM addresses and the complete Stellar StrKey checksum before submission.
- Quote source fees, destination output, gas, and available rate-limit capacity together.
- Authenticate the displayed destination network and recipient.
- Record the source transaction and messenger delivery identifier.
- Provide retry, gas top-up, and support instructions for delayed messages.
- Never imply that a source confirmation proves destination finality.