Sponsorship

Every transaction needs a fee, and fees are normally paid in DCC. That is a hurdle for someone who just received your token: before they can send it on, they first have to get DCC. Sponsorship removes it. When you sponsor your token, its holders can pay transaction fees in the token itself, and you pay the DCC fee to the network for them.

How It Works

1. The token’s issuer sends a Sponsor Fee transaction that sets minSponsoredAssetFee: the amount of the token that stands in for 0.001 DCC, one fee unit.

2. A holder sends a Transfer or Invoke Script transaction with feeAssetId set to the token and a fee in the token.

3. The fee in the token goes to the issuer. The issuer’s account pays the block generator the DCC equivalent: fee in token × 0.001 / minSponsoredAssetFee DCC.

Rule	Detail
Who can sponsor	Only the token’s issuer
Which tokens	Any token without an asset script; a smart asset can’t be sponsored
Which transactions can pay in the token	Transfer and Invoke Script
Minimum fee in the token	Fee units × minSponsoredAssetFee: 1 unit for a Transfer, 5 for an Invoke Script
Cost of the Sponsor Fee transaction	0.001 DCC
Turning it off	Send another Sponsor Fee transaction with minSponsoredAssetFee of 0

The issuer needs enough DCC to cover the fees it pays. If its DCC balance runs out, transactions that pay their fee in the token are rejected until it is topped up. Watch the issuer’s balance, or let users fall back to paying in DCC.

Choose minSponsoredAssetFee

minSponsoredAssetFee is in the token’s smallest unit. It sets the exchange rate you accept: with 2 decimals, 10 means 0.10 of your token buys 0.001 DCC of fee. Set it too low and users pay almost nothing while you pay full DCC fees; set it too high and fees feel expensive.

A user may pay more than the minimum. You then receive more of the token and pay more DCC, at the same rate.

Sponsor a Token with the SDK

This script issues a token, sponsors it, gives a user 10 tokens and has the user send 1 token while paying the fee in the token. Run it as in the Quick Start, with an issuer account that holds at least 1.003 DCC and any second account as the user:

npm install @decentralchain/transactions@5.0.1

import { issue, sponsorship, transfer, broadcast, waitForTx, libs } from '@decentralchain/transactions';

const nodeUrl = 'https://testnet-node.decentralchain.io';
const issuerSeed = 'issuer secret seed phrase here';
const userSeed = 'user secret seed phrase here';
const userAddress = libs.crypto.address(userSeed, '!');

// 1. Issue a token with 2 decimals (fee: 1 DCC)
const issueTx = issue(
  { name: 'GiftCard', description: 'Sponsored token example', quantity: 1_000_000, decimals: 2, reissuable: false, chainId: '!' },
  issuerSeed,
);
await broadcast(issueTx, nodeUrl);
await waitForTx(issueTx.id, { apiBase: nodeUrl, timeout: 120_000 });
const assetId = issueTx.id; // a token's ID is the ID of its Issue transaction

// 2. Enable sponsorship (fee: 0.001 DCC). 10 = 0.10 GiftCard stands in for 0.001 DCC of fee.
const sponsorTx = sponsorship({ assetId, minSponsoredAssetFee: 10, chainId: '!' }, issuerSeed);
await broadcast(sponsorTx, nodeUrl);
await waitForTx(sponsorTx.id, { apiBase: nodeUrl, timeout: 120_000 });

// 3. Give a user some tokens
const giveTx = transfer({ recipient: userAddress, amount: 1_000, assetId, chainId: '!' }, issuerSeed);
await broadcast(giveTx, nodeUrl);
await waitForTx(giveTx.id, { apiBase: nodeUrl, timeout: 120_000 });

// 4. The user sends tokens and pays the fee in the token, not in DCC
const userTx = transfer(
  {
    recipient: '31LAqgqVTLySNCPuYqgLAYhcgS76wvBaLr9',
    amount: 100,          // 1.00 GiftCard
    assetId,
    fee: 10,              // 0.10 GiftCard: the minimum for a transfer (1 fee unit)
    feeAssetId: assetId,
    chainId: '!',
  },
  userSeed,
);
await broadcast(userTx, nodeUrl);
await waitForTx(userTx.id, { apiBase: nodeUrl, timeout: 120_000 });
console.log('Token:', assetId, 'sponsored transfer:', userTx.id);

On the Testnet, the issuer’s DCC balance went from 8.997 to 7.994: 1 DCC to issue the token, 0.001 DCC each for the Sponsor Fee and the transfer to the user, and 0.001 DCC paid for the user’s fee. The user’s DCC balance did not change. The issuer’s token balance is 999,010: the 1,000,000 issued, minus the 1,000 sent to the user, plus the 10 the user paid as the fee.

To sponsor a token you already issued, skip step 1 and set assetId to the token’s ID.

Check a Token’s Sponsorship

GET /assets/details/{assetId} on any node returns minSponsoredAssetFee: the current amount, or null when the token isn’t sponsored.

curl https://testnet-node.decentralchain.io/assets/details/6r7zhATv5CghU4LWomoknB6uRMkDqW6wSbtZx8G32fiL

{"assetId": "6r7zhATv5CghU4LWomoknB6uRMkDqW6wSbtZx8G32fiL", "name": "GiftCard", "decimals": 2, "minSponsoredAssetFee": 10, "...": "..."}

Pay a Fee in a Sponsored Token

As a holder, you need nothing from the issuer: set feeAssetId to the token and fee to at least the minimum, as in step 4 of the script. Wallets do the same when you choose the token as the fee currency.

A node rejects the transaction if the token is not sponsored (Asset ... is not sponsored, cannot be used to pay fees), if the fee is below the minimum, or if the issuer can’t pay the DCC fee.