docs: add 'Register via DAO governance' article for generic-custom gateway by anegg0 · Pull Request #3260 · OffchainLabs/arbitrum-docs

anegg0 · 2026-05-05T01:48:24Z

Summary

Adds a dedicated how-to article documenting the standardized token registrations template that Offchain Labs published for token issuers who can't use the self-service registration path.

Context

The existing Configure generic-custom gateway bridging article covers the self-service path: the parent chain token implements ICustomToken and calls registerCustomL2Token + setGateway directly.

For non-upgradeable / immutable parent tokens, that path isn't available — registration must go through Arbitrum DAO governance using the privileged forceRegisterTokenToL2 and setGateways calls. Until now, that workflow was only documented in a forum announcement and a bash payload generator gist.

What this PR adds

New article: docs/build-decentralized-apps/token-bridging/configure-token-bridging/register-via-dao-governance.mdx
- Explains when to use the governance path vs. self-service.
- Shows what RegisterAndSetArbCustomGatewayAction does on-chain.
- Embeds the bash payload generator (sourced from the gist) with line-by-line context.
- Walks through Tally submission and the post-execution sequence (ArbSys → outbox → timelock → UpgradeExecutor → action contract → retryables).
- FAQ section covers irreversibility, why the proposal targets the ArbSys precompile, and template optionality.
Sidebar: new entry under Configure token bridging (alongside the three existing setup articles).
Cross-links from setup-generic-custom-gateway.mdx: the Step 1 "if your parent chain contract is not upgradeable" callout and the matching FAQ entry now point readers at the new article instead of the bare forum link.

Sources

Test plan

vercel build exits 0 with the new article rendered
New page exists at .vercel/output/static/build-decentralized-apps/token-bridging/configure-token-bridging/register-via-dao-governance/
Cross-links from setup-generic-custom-gateway.mdx resolve (build's strict link enforcement passes)
SME review for technical accuracy of the post-execution sequence (ArbSys → L1 outbox → timelock → UpgradeExecutor → action)
Confirm action address 0x997668Ee3C575dC060F80B06db0a8B04C9558969 and other governance constants are still current

🤖 Generated with Claude Code

…teway Documents the standardized token registration template for cases where the parent chain token can't self-register (non-upgradeable, missing ICustomToken). Covers the RegisterAndSetArbCustomGatewayAction contract, the calldata generator script, Tally proposal submission, and the post-execution sequence. Cross-links from setup-generic-custom-gateway.mdx (Step 1 prerequisite mention and FAQ entry). New sidebar entry under Configure token bridging. Sources: - https://github.com/OffchainLabs/governance/blob/main/src/gov-action-contracts/token-bridge/RegisterAndSetArbCustomGatewayAction.sol - https://forum.arbitrum.foundation/t/announcement-of-standardized-token-registrations-template/29764 - https://gist.github.com/gzeoneth/439dedc7bdd971345657a04c266daf00

vercel · 2026-05-05T01:48:29Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
arbitrum-docs	Error		May 13, 2026 6:05pm

anegg0 · 2026-05-05T03:43:44Z

Opened this PR on ArbitrumFoundation/docs#1183

Adds a substantive how-to article documenting the standardized token registration template (RegisterAndSetArbCustomGatewayAction) for proposers and delegates. Covers when the template applies, the action contract's on-chain effect, the calldata generator script, the AIP submission flow, the on-chain execution sequence after the proposal passes, and a delegate-focused 'what to verify' checklist. The lifecycle-anatomy-aip-proposal page now links to this local how-to instead of the external arbitrum-docs URL. The Arbitrum technical docs host a complementary issuer-side how-to with deeper deployment detail (OffchainLabs/arbitrum-docs#3260).

hummusonrails

Added a few comments for review.

hummusonrails · 2026-05-12T13:16:42Z

+}
+```
+
+Source: [`RegisterAndSetArbCustomGatewayAction.sol`](https://github.com/OffchainLabs/governance/blob/main/src/gov-action-contracts/token-bridge/RegisterAndSetArbCustomGatewayAction.sol).


Is the canonical source ArbitrumFoundation/governance or is itOffchainLabs/governance?

This article was a mistake. Harry recommended adding that content to the AF docs. Sorry for the noise.

hummusonrails · 2026-05-12T13:17:52Z

+Save the following script as `reg-arb-custom.sh`. Set `L1_TOKEN_ADDRESS` and `L2_TOKEN_ADDRESS` to your token's parent and child chain addresses. Leave the other constants alone — they reference live governance contracts on Ethereum and the canonical action address.
+
+```shell
+#!/usr/bin/env bash


Script is reproduced verbatim from the reference gist. The AF docs companion (ArbitrumFoundation/docs#1183) duplicates the same script. Two copies will drift silently. Consider a partial, an include, or at minimum a sync comment in both files.

Same reply as above: this duplicated content was a mistake, I'm shelving this article :)

hummusonrails · 2026-05-12T13:18:47Z

+  - `destination`: the L1 Timelock address printed by the script
+  - `data`: the calldata printed by the script
+
+Before publishing, post a draft on the [Arbitrum Foundation forum](https://forum.arbitrum.foundation/) for community review. Token registrations have historically passed without controversy, but the off-chain feedback step catches encoding mistakes.


I think the "Forum-then-Snapshot-then-Tally" is its own flow, not a sidenote inside the Tally step. The AF doc walks through it as ordered steps with a pointer to How to submit a DAO proposal. This article either does the same or scopes itself to calldata generation and hands off the rest. Currently it's halfway between, which leaves a reader thinking they can click "Create proposal" on Tally and be done.

hummusonrails · 2026-05-12T13:20:18Z

+  - `destination`: the L1 Timelock address printed by the script
+  - `data`: the calldata printed by the script
+
+Before publishing, post a draft on the [Arbitrum Foundation forum](https://forum.arbitrum.foundation/) for community review. Token registrations have historically passed without controversy, but the off-chain feedback step catches encoding mistakes.


Token registrations have historically passed without controversy...

Editorializing, in my opinion.. Either cite specific examples (BORING) or cut the sentence. As written it reads as reassurance that the vote is a formality, which could get the docs page in trouble if a future registration AIP fails.

hummusonrails · 2026-05-12T13:21:16Z


- As a chain owner, register via an [Arbitrum DAO](https://forum.arbitrum.foundation/) proposal.
- By wrapping your parent chain token and registering the wrapped version of your token.
+- Submit an [Arbitrum DAO proposal using the standardized token registrations template](/build-decentralized-apps/token-bridging/configure-token-bridging/register-via-dao-governance.mdx).


Great change here!

I that better?

anegg0 assigned mahsamoosavi May 5, 2026

vercel Bot deployed to Preview May 5, 2026 01:51 View deployment

anegg0 requested a review from mahsamoosavi May 5, 2026 01:51

anegg0 added the Needs SME review label May 5, 2026

anegg0 mentioned this pull request May 5, 2026

docs: add 'Register a token via DAO governance' how-to + AIP lifecycle cross-link ArbitrumFoundation/docs#1183

Open

4 tasks

anegg0 closed this May 5, 2026

anegg0 reopened this May 5, 2026

hummusonrails reviewed May 12, 2026

View reviewed changes

Merge branch 'master' into docs/standardized-token-registrations

7f31031

vercel Bot deployed to Preview May 13, 2026 03:19 View deployment

anegg0 added 2 commits May 12, 2026 20:43

remove duplicate content, this belongs in the AF repository

89136b4

add external link to AF docs

593c84c

vercel Bot had a problem deploying to Preview May 13, 2026 03:45 Failure

point DAO token registration to AF docs

4e139eb

vercel Bot had a problem deploying to Preview May 13, 2026 18:01 Failure

point second DAO token registration link to the AF doc

0af4c21

vercel Bot had a problem deploying to Preview May 13, 2026 18:05 Failure

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add 'Register via DAO governance' article for generic-custom gateway#3260

docs: add 'Register via DAO governance' article for generic-custom gateway#3260
anegg0 wants to merge 6 commits into
masterfrom
docs/standardized-token-registrations

anegg0 commented May 5, 2026

Uh oh!

vercel Bot commented May 5, 2026 •

edited

Loading

Uh oh!

anegg0 commented May 5, 2026

Uh oh!

hummusonrails left a comment

Uh oh!

hummusonrails May 12, 2026

Uh oh!

anegg0 May 13, 2026

Uh oh!

hummusonrails May 12, 2026

Uh oh!

anegg0 May 13, 2026

Uh oh!

hummusonrails May 12, 2026

Uh oh!

hummusonrails May 12, 2026

Uh oh!

hummusonrails May 12, 2026

Uh oh!

anegg0 May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

anegg0 commented May 5, 2026

Summary

Context

What this PR adds

Sources

Test plan

Uh oh!

vercel Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anegg0 commented May 5, 2026

Uh oh!

hummusonrails left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented May 5, 2026 •

edited

Loading