# 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:

{% code fullWidth="true" %}

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

{% endcode %}

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:

{% code fullWidth="true" %}

```solidity
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;
}
```

{% endcode %}

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

{% code fullWidth="true" %}

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

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://stargateprotocol.gitbook.io/stargate/v2-developer-docs/integrate-with-stargate/credit-allocation-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.