fee-bump

FeeBump Plugin

A Colibri plugin that wraps a Stellar Transaction in a Fee Bump Transaction so a designated account pays the fees.

It targets the SendTransaction step from @colibri/core. You can attach it to any convee pipe that includes steps.SEND_TRANSACTION_STEP_ID (for example, one created by createInvokeContractPipeline).

📚 Documentation | 💡 Examples

Quick start

Choose the integration style you need.

Using with a pipeline

Minimal usage — create the plugin with its configuration and add it to a pipeline that targets the SendTransaction step:

import { createFeeBumpPlugin } from "@colibri/plugin-fee-bump";
import { createInvokeContractPipeline, NetworkConfig } from "@colibri/core";

const networkConfig = NetworkConfig.TestNet();

const plugin = createFeeBumpPlugin({
  networkConfig,
  feeBumpConfig: {
    source: "G...FEEPAYER", // fee payer address
    fee: "10000000", // fee in stroops (1 XLM)
    signers: [
      /* signer objects */
    ],
  },
});

const pipeline = createInvokeContractPipeline({ networkConfig });
pipeline.use(plugin);

See the tests for full examples.

How it works

The plugin runs on the input of the SendTransaction step. It inspects the incoming payload, wraps and authorizes the transaction with a FeeBumpTransaction signed by the configured signers, and returns the modified input for the rest of the pipeline.

API

• createFeeBumpPlugin(options) — create plugin instance
• FEE_BUMP_PLUGIN_ID — plugin id
• FEE_BUMP_PLUGIN_TARGET — pipeline step where it should be added (SendTransaction)
• Code and ERROR_PLG_FBP — stable error codes and constructors
• FeeBumpPluginConfig, FeeBumpPluginNetworkConfig, and FeeBumpPluginArgs — plugin configuration types
• FeeBumpPluginSigner — union of the supported outer-envelope signer capabilities
• FeeBumpEnvelopeSigner — signer that adds a decorated envelope signature
• FeeBumpPreAuthorizedTransactionSigner — signer that validates an exact pre-authorized outer transaction hash
• FeeBumpPluginSignerIdentity and FeeBumpSignableTransaction — interfaces for custom fee-bump signer implementations

The package also re-exports Core's branded SignerKey, Ed25519PublicKey, ContractId, PreAuthTx, Sha256Hash, and SignedPayload types for custom signer implementations.

For concrete examples, refer to the unit and integration tests in src/.

Options

createFeeBumpPlugin accepts an options object with the following fields:

• networkConfig (required) — Colibri network configuration (for example, NetworkConfig.TestNet()). The plugin uses this configuration when building transactions.

• feeBumpConfig (required) — Configuration for the fee bump behavior:

  • source (string, required) — The Stellar account address that will pay the fee (fee source).
  • fee (string, required) — Fee amount in stroops to set on the FeeBumpTransaction as base fee* (e.g. "10000000" equals 1 XLM).
  • signers (array, required) — Envelope or pre-authorized transaction signer objects used to authorize the fee-bump source. This includes LocalSigner, HashXSigner, Ed25519SignedPayloadSigner, and PreAuthorizedTransactionSigner.

*Since this value defines a base fee, the total amount set as max network fee will be this value multiplied by the number of operations in the inner envelope plus one(the fee bump wrap). So, for contract invocations for example this will be 2 times the value set as it only contains one operation plus the wrapper.

Example:

createFeeBumpPlugin({
  networkConfig: NetworkConfig.TestNet(),
  feeBumpConfig: {
    source: feePayer.address(),
    fee: "10000000",
    signers: [feePayer.signer()],
  },
});