Skip to content

OffchainLabs/arbitrum-docs / .agents/skills/arbitrum-best-practices

arbitrum-best-practices

Verified

Arbitrum L2 development best practices. Use when implementing bridges, Orbit chains, SDK integrations, or debugging cross-chain transactions. Triggers on Arbitrum, L2, rollup, bridge, retryable, Orbit, Nitro, or cross-chain contexts.

rules/sdk-gateway-registration.md

View on GitHub
---
title: Register Tokens Before Bridging
impact: HIGH
impactDescription: enables token bridging
tags: sdk, gateway, token, bridge
---

## Register Tokens Before Bridging

Custom ERC20 tokens must be registered with a gateway before bridging. Attempting to bridge an unregistered token fails or sends tokens to the wrong address.

**Incorrect (bridge without checking registration):**

```typescript
// Bad: Bridging without verifying registration
await bridger.deposit({ erc20L1Address: token, amount, ... })
// Fails if token not registered with gateway
```

**Correct (check registration first):**

```typescript
// Good: Verify gateway registration before bridging
const gateway = await bridger.getL1GatewayAddress(token, l1Provider)
if (gateway === ZeroAddress) {
  throw new Error('Token not registered - cannot bridge')
}
await bridger.deposit({ erc20L1Address: token, amount, ... })
```

| Gateway | Use Case |
|---------|----------|
| Standard ERC20 | Most tokens (auto-mint/burn on L2) |
| Custom Gateway | Rebasing, fee-on-transfer tokens |
| WETH Gateway | Wrapped ETH (pre-deployed) |

Registration requires deploying an L2 token implementing `IArbToken` (bridgeMint/bridgeBurn).

For gateway setup, see [Token Bridging](https://docs.arbitrum.io/build-decentralized-apps/token-bridging/bridge-tokens-programmatically).
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall