How Transaction Sponsorship Works

Transaction sponsorship lets your users sign transactions while your developer-controlled wallet covers the network fees. This guide explains the architecture, the end-to-end flow, and how the SDK manages UTXOs automatically.

TL;DR

• Create and fund a developer-controlled wallet that pays fees
• Build your transaction using a “static” placeholder UTXO and change address from the SDK
• Call sponsorTx() to swap in a real UTXO and apply the developer wallet signature
• Have the user sign and submit the final sponsored transaction
• The SDK automatically manages UTXO creation and chains prep transactions when needed

What are the key concepts?

Step-by-Step Flow

import { Web3Sdk } from "@utxos/sdk";
 
const sdk = new Web3Sdk({
  projectId: process.env.NEXT_PUBLIC_UTXOS_PROJECT_ID,
  apiKey: process.env.UTXOS_API_KEY,
  network: "testnet",
  privateKey: process.env.UTXOS_PRIVATE_KEY,
  fetcher: provider,
  submitter: provider,
});
 
// Get placeholder inputs
const staticInfo = sdk.sponsorship.getStaticInfo();
 
// Build with your preferred transaction builder
const txBuilder = yourTransactionBuilder
  // Add your business logic (mints, outputs, scripts, etc.)
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "1000000" }])
 
  // Required: Set change address from static info
  .changeAddress(staticInfo.changeAddress)
 
  // Required: Add static UTXO as input
  .txIn(
    staticInfo.utxo.input.txHash,
    staticInfo.utxo.input.outputIndex,
    staticInfo.utxo.output.amount,
    staticInfo.utxo.output.address,
    0
  )
 
  // Optional: Add collateral if your transaction requires it
  .txInCollateral(
    staticInfo.collateral.input.txHash,
    staticInfo.collateral.input.outputIndex,
    staticInfo.collateral.output.amount,
    staticInfo.collateral.output.address
  );
 
const unsignedTx = await txBuilder.complete();

const sponsorResult = await sdk.sponsorship.sponsorTx({
  sponsorshipId: "your_sponsorship_id",
  tx: unsignedTx,
});
 
if (!sponsorResult.success) {
  throw new Error(sponsorResult.error);
}
 
// sponsorResult.data contains the sponsored CBOR transaction

// User adds their signature(s)
const signedTx = await userWallet.cardano.signTx(sponsorResult.data, true);
 
// Submit to the network
const txHash = await provider.submitTx(signedTx);
 
console.log(`Transaction submitted: ${txHash}`);

What happens under the hood?

UTXO Availability Check

1. Fetch all UTXOs from the developer-controlled wallet
2. Exclude UTXOs pending in the mempool to prevent double-spends
3. The remaining set forms the available pool

Automated UTXO Pool Maintenance

The SDK monitors your UTXO pool and takes action when needed:

1. Identify UTXOs that are not the standard sponsorship amount
2. Flag sponsorship-sized UTXOs pending longer than the configured threshold
3. Build a “prepare UTXO” transaction to consolidate and create fresh UTXOs
4. Chain this preparation with the sponsorship request automatically

UTXO Selection

The SDK randomly selects an eligible UTXO from the available pool for each sponsorship request. Random selection distributes load and reduces contention.

Transaction Rewrite

1. Parse the provided CBOR transaction
2. Remove static placeholder inputs and the static change output
3. Add the selected real sponsorship UTXO as input
4. Set change to the developer-controlled wallet address
5. Return the rewritten CBOR transaction

API Reference

sdk.sponsorship.getStaticInfo(amount?)

Returns placeholder information for building sponsored transactions.

Returns:

{
  changeAddress: string;
  utxo: {
    input: { txHash: string; outputIndex: number };
    output: { amount: string | bigint; address: string };
  };
  collateral: {
    input: { txHash: string; outputIndex: number };
    output: { amount: string | bigint; address: string };
  };
}

sdk.sponsorship.sponsorTx(options)

Sponsors a transaction by replacing static placeholders with real UTXOs.

Returns:

{
  success: boolean;
  data?: string;  // CBOR-encoded sponsored transaction
  error?: string; // Error message if success is false
}

Error Handling

Security Best Practices

• Rate limit sponsorship requests to prevent abuse and UTXO exhaustion
• Monitor your UTXO pool for minimum count, standard size, and pending ratio
• Use dedicated change addresses for simpler accounting and auditing
• Set spending limits per user or per time period in your application logic

Configuration Recommendations

FAQ

Can I use any transaction builder?

Yes. Any builder that can set a change address, add inputs, and produce CBOR output works with sponsorship.

What format does sponsorTx expect?

A CBOR-encoded transaction as a hex string.

Does the SDK always create consolidation transactions?

Only when your available UTXO pool falls below the configured target or contains stale UTXOs that need refreshing.

Who signs what?

The developer-controlled wallet signs to provide the fee input. The user signs their parts (spending inputs, mints, scripts) before submission.

How many confirmations before new sponsorship UTXOs are usable?

Pending UTXOs are excluded until confirmed. Follow your network’s standard confirmation policy.