> For the complete documentation index, see [llms.txt](https://docs.astralbeam.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.astralbeam.io/operators/admin-commands.md). # Admin Commands Administrative commands for managing bridge contracts. These commands require private keys and submit transactions. ## Usage ```bash bridge-cli admin [options] ``` View all admin commands: ```bash bridge-cli admin --help ``` *** ## Ethereum Commands ### register-token Register an ERC-20 token on MultiSigLocker. ```bash bridge-cli admin register-token \ --erc20
\ --casper-hash \ --network ``` **Options:** | Option | Required | Description | | ------------------------- | -------- | -------------------------------- | | `--erc20
` | Yes | ERC-20 token address | | `--casper-hash ` | Yes | Casper CEP-18 contract hash | | `-n, --network ` | No | EVM network (defaults to config) | **Example:** ```bash bridge-cli admin register-token \ --erc20 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 \ --casper-hash hash-62d62d5cb43d095b9096ecfe3a3f2bd4d2a1df4020cd9cda94594edb77fedf38 \ --network sepolia ``` *** ### update-token-mapping Update the Casper hash for an already registered ERC-20 token. ```bash bridge-cli admin update-token-mapping \ --erc20
\ --casper-hash \ --network ``` *** ### deploy-wrapped-token Deploy a wrapped ERC-20 token on Ethereum for a Casper-native CEP-18 token. ```bash bridge-cli admin deploy-wrapped-token \ --casper-hash \ --name \ --symbol \ --decimals \ --network ``` **Example:** ```bash bridge-cli admin deploy-wrapped-token \ --casper-hash hash-abc123... \ --name "Wrapped CSPR Test Token" \ --symbol "wTEST" \ --decimals 9 \ --network sepolia ``` *** ### replace-wrapped-token Replace an existing zero-supply Casper-native wrapper with the V13 bridge-only-burn implementation. This recovery command is intended for testnet wrappers deployed before the bridge-only-burn hardening; it does not migrate balances and refuses to run unless the locker is fully paused and the old wrapper's total supply is exactly zero. ```bash bridge-cli admin replace-wrapped-token \ --casper-hash hash-<64-hex-character-CEP-18-hash> \ --expected-old-wrapper 0x \ --network sepolia ``` The command is hard-blocked outside Sepolia, Base Sepolia, and Polygon Amoy. It binds the operation to the exact approved old-wrapper address and validates that the wrapper still exposes the legacy direct-burn API, plus V13, admin ownership, full pause, zero supply, mappings, and enumeration before submission. After confirmation it verifies the replacement event, bytecode, both mappings, enumeration, immutable bridge/hash values, and that direct `burn(uint256)` plus non-bridge `burnFrom(address,uint256)` calls revert while locker-authorized zero-amount `burnFrom` succeeds. Use `--yes` only for controlled non-interactive testnet operations. After replacement, retire the old reverse mapping and install the new Casper TokenFactory mapping for the same EVM chain ID while the locker remains fully paused: ```bash bridge-cli admin casper-unregister-wrapped-token \ --wrapped \ --chain-id \ --expected-cep18 hash-<64-hex-character-CEP-18-hash> bridge-cli admin casper-update-native-token-mapping \ --cep18 hash-<64-hex-character-CEP-18-hash> \ --chain-id \ --wrapped # Exact read-back: old reverse mapping must be absent; both new directions must agree. bridge-cli casper TokenFactory get_native_token # Expected: (not registered as wrapped token) bridge-cli casper TokenFactory get_wrapped_token hash- # Expected: bridge-cli casper TokenFactory get_native_token # Expected: ``` Keep the locker fully paused until those three reads and relayer configuration resolve the replacement. The unregister command itself requires `casper-test`, an approved EVM testnet chain ID, and an exact live reverse-mapping match; a stale or absent mapping aborts before confirmation. This procedure is authorized for **one designated zero-supply Casper-native wrapper on testnet only**; never use it for mainnet or a second/repeated replacement. Record a real round trip with the production CLI after unpausing under the approved procedure: ```bash # Capture Casper source and EVM destination balances before each operation. bridge-cli admin lock-native --cep18 hash- --amount \ --recipient --network # Assert NativeTokenLocked identifies the CEP-18, recipient, amount, nonce, and chain ID. # Assert the EVM balance and totalSupply of each increase by . bridge-cli admin burn-wrapped --wrapped --amount \ --recipient --network # Assert exactly one WrappedBurned identifies , recipient type/hash, # amount, nonce, and chain ID. Assert EVM balance/supply decrease by and # the Casper CEP-18 balance increases by after unlock. ``` Preserve both source transaction IDs, both destination transaction/deploy IDs, exact decoded event fields, and all four before/after balance and supply values. The old wrapper remains deployed but is no longer recognized by the locker. *** ### lock-tokens Lock ERC-20 tokens on EVM chain to mint CEP-18 on Casper. ```bash bridge-cli admin lock-tokens \ --erc20
\ --amount \ --recipient \ --network \ [--skip-fee] ``` **Options:** | Option | Required | Description | | ------------------------- | -------- | -------------------------------------------- | | `--erc20
` | Yes | ERC-20 token address | | `--amount ` | Yes | Amount in smallest unit (wei) | | `--recipient ` | Yes | Casper recipient (`account-hash-xxx` or hex) | | `-n, --network ` | No | Target EVM network | | `--skip-fee` | No | Skip bridge fee (testing) | **Example:** ```bash bridge-cli admin lock-tokens \ --erc20 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 \ --amount 100000000 \ --recipient account-hash-abc123... \ --network sepolia ``` *** ### update-relayer-set Update the relayer set on MultiSigLocker. ```bash bridge-cli admin update-relayer-set \ --relayers \ --threshold ``` **Example:** ```bash bridge-cli admin update-relayer-set \ --relayers 0xabc...,0xdef...,0x123...,0x456...,0x789... \ --threshold 3 ``` *** ### get-relayer-set Query current relayer configuration from MultiSigLocker. ```bash # Single network bridge-cli admin get-relayer-set --network sepolia # All configured networks bridge-cli admin get-relayer-set --all ``` *** ### set-min-lock-amount Set the global default minimum lock amount on MultiSigLocker. This value is specified in "token units" and is automatically scaled by each token's decimals. ```bash bridge-cli admin set-min-lock-amount --amount --network ``` **Options:** | Option | Required | Description | | ------------------------- | -------- | ------------------------------------------ | | `--amount ` | Yes | Minimum in token units (e.g., 1 = 1 token) | | `-n, --network ` | No | Target EVM network | **Example:** ```bash # Set global minimum to 1 token unit # For USDC (6 decimals): enforces minimum of 1 USDC (1,000,000 wei) # For WETH (18 decimals): enforces minimum of 1 WETH (1e18 wei) bridge-cli admin set-min-lock-amount --amount 1 --network sepolia ``` **Security Note:** This protects against dust attacks and DoS vectors. See [Security Model](/security/security.md#anti-dusting-protection). *** ### set-token-min-lock Set minimum lock amount for a specific token. Unlike the global minimum, this accepts decimal amounts and is NOT automatically scaled. ```bash bridge-cli admin set-token-min-lock \ --token
\ --amount \ --network ``` **Options:** | Option | Required | Description | | ------------------------- | -------- | --------------------------------------------- | | `--token
` | Yes | ERC-20 token address | | `--amount ` | Yes | Minimum in decimal notation (e.g., 0.1, 10.5) | | `-n, --network ` | No | Target EVM network | **Examples:** ```bash # Set min lock to 0.1 WETH bridge-cli admin set-token-min-lock \ --token 0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14 \ --amount 0.1 \ --network sepolia # Set min lock to 10 USDC bridge-cli admin set-token-min-lock \ --token 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 \ --amount 10 \ --network sepolia # Remove per-token minimum (revert to global) bridge-cli admin set-token-min-lock \ --token 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 \ --amount 0 \ --network sepolia ``` **Query Current Minimums:** ```bash # Get global minimum bridge-cli evm --network sepolia MultiSigLocker minLockAmount # Get effective minimum for a token bridge-cli evm --network sepolia MultiSigLocker getMinLockAmountForToken 0x1c7D... # Get raw per-token setting (0 if using global) bridge-cli evm --network sepolia MultiSigLocker getTokenMinLockAmount 0x1c7D... ``` *** ## Casper Commands ### deploy-token Deploy/register an ERC-20 token mapping on TokenFactory. ```bash bridge-cli admin deploy-token \ --erc20
\ --name \ --symbol \ --decimals \ [--skip-decimals-check] ``` Before submitting `deploy_token`, the CLI verifies `--decimals` against the source ERC-20's live on-chain `decimals()`. A mismatch aborts the deploy — a wrong decimals value would cause systematic over/under-crediting on every future mint for that mapping, and it cannot be corrected after registration. Use `--skip-decimals-check` only for nonstandard tokens without a `decimals()` view or when the source RPC is intentionally unavailable. *** ### get-cep18 Get the CEP-18 address for a registered ERC-20 token. ```bash bridge-cli admin get-cep18 \ --erc20
\ --chain ``` **Example:** ```bash bridge-cli admin get-cep18 \ --erc20 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 \ --chain 11155111 ``` *** ### burn-tokens Burn CEP-18 tokens on Casper to unlock ERC-20 on EVM. ```bash bridge-cli admin burn-tokens \ --cep18 \ --amount \ --recipient \ --chain \ [--skip-fee] ``` **Example:** ```bash bridge-cli admin burn-tokens \ --cep18 hash-62d62d5cb43d095b9096ecfe3a3f2bd4d2a1df4020cd9cda94594edb77fedf38 \ --amount 100000000 \ --recipient 0x1234567890abcdef1234567890abcdef12345678 \ --chain 11155111 ``` *** ## Casper-Native Token Commands ### lock-native Lock CEP-18 tokens on Casper to mint wrapped ERC-20 on EVM. ```bash bridge-cli admin lock-native \ --cep18 \ --amount \ --recipient \ --chain \ [--skip-fee] ``` *** ### burn-wrapped Burn wrapped ERC-20 tokens on EVM to unlock CEP-18 on Casper. ```bash bridge-cli admin burn-wrapped \ --wrapped
\ --amount \ --recipient \ [--skip-fee] ``` *** ## Casper Contract Administration ### casper-pause Pause TokenFactory on Casper. ```bash bridge-cli admin casper-pause ``` *** ### casper-unpause Unpause TokenFactory on Casper. ```bash bridge-cli admin casper-unpause ``` *** ### casper-propose-admin / casper-accept-admin Transfer admin on TokenFactory (two-step). The current admin proposes; the proposed admin accepts with their own key. ```bash # Step 1: current admin key bridge-cli admin casper-propose-admin --address # Step 2: proposed admin key bridge-cli admin casper-accept-admin ``` *** ### casper-register-token-mapping Register a token mapping on TokenFactory. ```bash bridge-cli admin casper-register-token-mapping \ --erc20
\ --cep18 \ --chain-id ``` *** ### casper-update-native-token-mapping Update native token mapping on TokenFactory. ```bash bridge-cli admin casper-update-native-token-mapping \ --cep18 \ --chain-id \ --wrapped
``` *** ### casper-set-eth-client Set EthClient address on TokenFactory. ```bash bridge-cli admin casper-set-eth-client --hash ``` *** ### casper-set-erc20-locker Set the ERC20Locker address on TokenFactory for a specific source EVM chain (per-chain mapping since v7 / BRIDGE-E2E-1). ```bash bridge-cli admin casper-set-erc20-locker --chain-id --address ``` Both options are required. The contract entry point takes `source_chain_id` and `erc20_locker`. > **Post-upgrade pitfall:** an in-place `upgrade_package` to v7 leaves the `erc20_lockers` mapping **empty** (it is seeded only in the constructor path). Every mint from an unseeded chain reverts with `Erc20LockerNotSet` (60045). Seed each supported chain explicitly after upgrading. *** ## Casper EthClient Administration ### casper-add-relayer Add a relayer to EthClient on Casper. ```bash bridge-cli admin casper-add-relayer --address ``` *** ### casper-remove-relayer Remove a relayer from EthClient on Casper. ```bash bridge-cli admin casper-remove-relayer --address ``` *** ### casper-set-threshold Set signature threshold on EthClient. ```bash bridge-cli admin casper-set-threshold --threshold ``` *** ### casper-propose-ethclient-admin / casper-accept-ethclient-admin Transfer admin on EthClient (two-step — same propose/accept pattern as TokenFactory). ```bash # Step 1: current admin key bridge-cli admin casper-propose-ethclient-admin --address # Step 2: proposed admin key bridge-cli admin casper-accept-ethclient-admin ``` *** ## Environment Requirements Admin commands require private keys configured in `.env`: ```bash # For EVM operations ETH_PRIVATE_KEY=0x... # For Casper operations CASPER_PRIVATE_KEY_PATH=./keys/secret_key.pem ``` *** ## Common Errors ```bash # Not admin Error: Caller 0x... is not admin (0x...) # Token not registered Error: Token is not registered on MultiSigLocker # Insufficient fee Error: Insufficient bridge fee sent # Missing key Error: ETH_PRIVATE_KEY not configured in .env ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.astralbeam.io/operators/admin-commands.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.