Stargatebridge fees and transfer quote components

The token difference gives the protocol charge

In a Stargate v2 quote, the protocol charge equals the quoted amount sent minus the quoted amount received, using matching token units. A positive difference represents a charge. A negative difference represents a net token reward where the pool rules permit one. The quoted output already incorporates that adjustment, so subtracting the protocol charge again would count it twice.

The quoteOFT function returns token amounts, fee details and transfer limits. If the requested input exceeds the reported maximum, it quotes the capped amount instead. Separately, quoteSend returns the messaging payment. A zero token charge can therefore accompany a payable messaging fee. Source transaction gas adds another expense outside the token adjustment.

Token units and native currency need separate accounting

Transfer-token amounts

The v2 token quote expresses its receipt amounts in the source asset's local decimal units. These integers need the asset's decimal scaling before they become readable token quantities. Shared decimals provide the common precision that the protocol uses across chains. Comparing raw balances from different decimal systems can create an apparent fee that is simply a unit mismatch.

Wallet funding

An ERC-20 pool transfer supplies the transfer token separately from the native messaging payment. A native-coin pool transfer includes the principal alongside that payment in the transaction value. The principal remains the asset that the user transfers. Comparing expenses across different currencies requires a common valuation basis; adding their raw quantities does not produce a meaningful total.

FeeLibV1 applies amount bands and pool conditions

FeeLibV1 uses destination-specific token fee and reward settings on Stargate v2 routes configured with this library.

The fee-bearing amount

The fee-bearing amount selects one of three configured bands, whose rate applies to that whole amount. For positive fee-bearing amount B and positive rate r, FeeLibV1 calculates the fee in shared units as floor(B × r / 1,000,000) + 1. A zero configured rate produces no library fee. In this formula, B counts integer shared units and r is the selected band's configured rate in parts per million.

Deficit-related rewards

For a source Pool instance with a positive deficit and nonzero reward rate, the reward calculation covers the amount up to that deficit. Any excess enters the fee calculation. A Hydra OFT origin uses the fee branch instead. Pools cap a positive net reward at the available treasury balance, so the raw reward calculation alone does not establish the final output.

Bus riders pay a configured share of messaging costs

A v2 Bus rider pays a destination-specific fare that distinguishes ordinary transfers from transfers requesting native currency on arrival. The Bus fare estimator divides the batch's quoted native messaging fee by the passenger count supplied to that calculation. The Planner sets the fares that riders actually pay. This distinction prevents treating the current queue occupancy as a promise that every additional rider will reduce an existing rider's payment.

Taxi obtains a quote for an individual message and avoids the Bus batching wait. Its messaging price reflects the message and execution options. A meaningful price comparison keeps the route, asset and amount consistent, alongside any destination options. Comparing a plain Bus payout with a Taxi transfer that includes a contract call compares different services.

View image file

Destination gas funding changes what the quote pays for

Adding destination gas funds a native-currency top-up alongside the bridged asset. When the top-up succeeds, the recipient can use that currency for later destination transactions. The extra payment includes value intended for delivery, alongside the messaging costs. Source payment and destination delivery also have their own currency units.

The v2 transfer interface permits only the default destination-gas amount for Bus transfers. Taxi allows a custom amount. The available top-up therefore depends on the selected mode, and the default Bus amount does not establish a universal allowance across every destination.

The messaging quote already prices its selected execution options. Adding a second estimate for that same destination execution can count the service twice. Later wallet activity has its own transaction costs, even when the optional top-up supplies the currency that pays them.

Approval gas changes the source wallet expense

An ERC-20 transfer may require approval when the existing token allowance is insufficient. If that approval uses a separate transaction, it adds source-network gas before the transfer transaction. An existing sufficient allowance changes that expense. The bridge quote alone therefore cannot establish the gas cost of every transaction that a particular wallet needs.

Source execution gas remains separate from the messaging payment, even when both use the same native currency. On EVM source networks, execution that reverts can still consume gas. A failed transfer therefore does not establish that the wallet spent nothing.

Destination contract calls require their own execution budget

A composed Taxi transfer needs execution funding for its destination callback in addition to token delivery. The receiving contract's logic determines the callback's gas requirements. The quote must include the execution options for that actual operation. A gas allowance copied from an unrelated callback does not establish sufficient funding.

Bus does not support composed destination calls. A downstream swap also has its own pricing conditions, separate from the bridge's token adjustment. Those application costs belong in a comparison of the full requested operation, while a plain transfer quote covers a narrower task.

Transfer size and changing state affect the quote

A different transfer amount can cross a configured fee band or exceed the portion eligible for a pool reward. The effective percentage can therefore change with the amount. Available route credit also constrains the transfer. Paying a larger messaging fee does not increase that credit.

The minimum-output parameter constrains the token result that execution will accept. The v2 send rounds the minimum down to shared precision and reverts if the adjusted output falls below it or equals zero. Messaging prices can also change as gas prices or service charges move. A quote describes the selected inputs and pricing state; an older payment amount may no longer cover the required fare.