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:

1. For each pool: pool balance >= local unallocated credits + sum of allocated credits in remote paths

2. 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:

paths[_sendParam.dstEid].decreaseCredit(amountOutSD); // remove the credit from the path

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:

if (amountInSD > amountOutSD) {
    // fee
    uint64 fee = amountInSD - amountOutSD;
    paths[localEid].decreaseCredit(fee);
    poolBalanceSD -= fee;
} else if (amountInSD < amountOutSD) {
    // reward
    uint64 reward = amountOutSD - amountInSD;
    paths[localEid].increaseCredit(reward);
    poolBalanceSD += reward;
}

When redeem() is called instead and tokens are redeemed locally it subtracts redeemed amount from local credits:

amountSD = paths[localEid].tryDecreaseCredit(amountSD);