Shelby USD Sponsorship

Shelby is a storage protocol that uses Aptos as its coordination layer. Certain Shelby operations, such as registering blobs, require payment in ShelbyUSD (in addition to the usual gas costs in APT). Normally, your users would need to hold and spend ShelbyUSD to perform these operations.

With ShelbyUSD sponsorship enabled, your gas station can cover these ShelbyUSD costs on behalf of your users, providing a smoother user experience where users don’t need to hold any assets at all.

How It Works

1. Standard Gas Sponsorship: Your gas station pays APT gas fees for transactions.
2. ShelbyUSD Sponsorship: Your gas station additionally covers ShelbyUSD storage costs.

When you enable ShelbyUSD sponsorship:

• The gas station fee payer account will be funded with ShelbyUSD in addition to APT.
• Your users call Shelby functions with the _with_sponsor suffix (the Shelby SDK handles this automatically).
• The gas station signs as both a fee payer (for APT gas) and a secondary signer (for ShelbyUSD sponsorship).

How to create a gas station with ShelbyUSD sponsorship

The option to enable ShelbyUSD sponsorship only appears when you’re configuring a gas station for the Shelby contract on shelbynet or testnet. When creating a gas station, input the contract address.

Shelbynet

Testnet

Once you have created the gas station, record the fee payer address and API key.

Client Integration

Using the Shelby SDK (Recommended)

The @shelby-protocol/sdk has built-in support for ShelbyUSD sponsorship. When you pass usdSponsor to the SDK, it automatically:

1. Uses the _with_sponsor variants of entry functions (e.g., register_blob_with_sponsor instead of register_blob).
2. Includes your gas station’s fee payer as a secondary signer in the transaction.
3. Routes the transaction through the gas station for co-signing via the transaction submitter plugin.

Install the required packages:

pnpm add @shelby-protocol/sdk @aptos-labs/gas-station-client @aptos-labs/ts-sdk

Set up the gas station client and Shelby blob client:

import { ShelbyBlobClient } from "@shelby-protocol/sdk";
import { GasStationClient, GasStationTransactionSubmitter } from "@aptos-labs/gas-station-client";
import { AccountAddress, Network } from "@aptos-labs/ts-sdk";
 
// 1. Create a gas station client with your API key.
const gasStationClient = new GasStationClient({
  network: Network.SHELBYNET,
  apiKey: "YOUR_GAS_STATION_API_KEY",
});
 
// 2. Wrap it in a transaction submitter plugin.
const transactionSubmitter = new GasStationTransactionSubmitter(gasStationClient);
 
// 3. Create a ShelbyBlobClient with ShelbyUSD sponsorship enabled.
const blobClient = new ShelbyBlobClient(
  {
    network: Network.SHELBYNET,
    aptos: {
      pluginSettings: {
        TRANSACTION_SUBMITTER: transactionSubmitter,
      },
    },
  },
  {
    // The feePayerAddress is your gas station's fee payer, which you can find on the
    // gas station overview page.
    usdSponsor: {
      feePayerAddress: AccountAddress.from("0x<your-fee-payer-address>"),
    },
  },
);

From here, all blob operations automatically use the sponsored variants:

// The SDK calls register_blob_with_sponsor under the hood and routes
// the transaction through the gas station for co-signing.
await blobClient.upload({
  blobData: myData,
  signer: userAccount,
  blobName: "example.txt",
  expirationMicros: Date.now() * 1000 + 86400_000_000,
});

Details

When ShelbyUSD sponsorship is enabled, additional functions become available that end with _with_sponsor. These are special variants that allow the gas station to authorize ShelbyUSD payments on behalf of the user.

For example:

• register_blob → register_blob_with_sponsor
• register_multiple_blobs → register_multiple_blobs_with_sponsor
• increase_expiration_time → increase_expiration_time_with_sponsor

You can use both types of sponsorship simultaneously so your users don’t need to hold any tokens at all.

When both are enabled, the gas station signs as both the fee payer (for APT gas) and a secondary signer (for costs in ShelbyUSD).