Credit Allocation System
Introduction
Credits are a way of tracking inflows and outflows of tokens in the protocol.
Instant Guaranteed Finality
Thanks to the credit allocation mechanism, Stargate maintains a crucial property of cross-chain systems, which is Instant Guaranteed Finality.
Instant Guaranteed Finality means that Stargate swaps are settled locally immediately, without the risk of revert, rollback or double spending on the source chain. You still need to wait for the tokens to be delivered on the destination chain by the underlying messaging protocol, but Stargate ensures the success of the destination transaction.
It is possible because Stargate was designed to hold following invariant true:
For each pool: pool balance >= local unallocated credits + sum of allocated credits in remote paths
Sum of pool balances >= sum of OFT supplies + sum of total values locked
AI Planning Module
Credits in Stargate V2 are handled by the AI Planning Module (Planner in codebase), which conducts automated credit rebalancing within the protocol. It’s role is simply to ensure credits are allocated and reallocated to pathways that see the most volume. Stargate V1 had static credits on pathways. Stargate V2 has dynamic credits and therefore much greater capital efficiency.
Code related to rebalancing credits can be found in CreditMessaging
contract.
Pathway credit operations
In rare cases you may run into some issues with the credits mechanism. For example when there's not enough credits PathLib
might revert with Path_InsufficientCredit
. In this section you can find high-level overview of credit operations in Stargate to assist you in debugging.
StargateBase contract
In the PathLib
library there are methods to increase and decrease credits for paths to different endpoints. These functions are called both by Pool and Hydra tokens. In StargateBase
contract there's a function _inflowAndCharge()
triggered when value is transferred from an account into Stargate to execute a swap as part of sendToken()
call.
The system reduces the credits for the destination pathway where the user is transferring tokens:
There are also two methods that can be indirectly called by the Planner: sendCredits()
and receiveCredits()
to increase or decrease credit balances for different paths.
StargatePool contract
The StargatePool
contract also performs operations on credits as part of its lifecycle.
It increases/decreases local credits based on fee or rewards in redeemSend()
when redeeming tokens on destination endpoint:
When redeem()
is called instead and tokens are redeemed locally it subtracts redeemed amount from local credits:
Last updated