How-to: Configure rate limits and transfer caps

​

How the throttles behave

• Rate limit. Caps the net outbound amount of a token in a sliding window. Net outbound is the outbound amount minus the inbound amount received during the same window. The default window length is six hours. Setting the rate limit to 0 blocks all outbound transfers of the token. After configuration, always verify the limit is non-zero before your first crossChainTransfer; a common mistake is configuring with rateLimit: 0 and skipping this guide.
• Max transfer amount. Caps the size of a single outbound transfer transaction. Applies on top of the rate limit to prevent oversize single transfers regardless of the headroom remaining in the rate-limit window.

• A user transfers 300,000 out and 100,000 in during the window. Net outbound consumed is 200,000. Remaining headroom: 800,000.
• A second user attempts to transfer 900,000 out in the same window. The transfer reverts because net outbound would exceed 1,000,000.

​

Prerequisites

• Obtained the tokenId for the token you want to configure.
• Confirmed the wallet you’ll use holds the operator role for that token’s TokenManager.

​

Steps

const tokenManager: `0x${string}` = await publicClient.readContract({
  address: serviceAddress,
  abi: serviceAbi,
  functionName: "resolveTokenManager",
  args: [tokenId],
});

await walletClient.writeContract({
  address: tokenManager,
  abi: tokenManagerAbi,
  functionName: "setRateLimit",
  args: [5_000_000n * 10n ** 18n],
});

await walletClient.writeContract({
  address: tokenManager,
  abi: tokenManagerAbi,
  functionName: "setMaxTransferAmount",
  args: [500_000n * 10n ** 18n],
});

await walletClient.writeContract({
  address: tokenManager,
  abi: tokenManagerAbi,
  functionName: "setRateLimitWindow",
  args: [3600n], // 1 hour
});

const [rateLimit, maxTransferAmount] = await Promise.all([
  publicClient.readContract({
    address: tokenManager,
    abi: tokenManagerAbi,
    functionName: "rateLimit",
  }),
  publicClient.readContract({
    address: tokenManager,
    abi: tokenManagerAbi,
    functionName: "maxTransferAmount",
  }),
]);

console.log({ rateLimit, maxTransferAmount });
if (rateLimit === 0n) {
  throw new Error("rateLimit is 0: outbound transfers are blocked");
}