_meta.json

{
  "ApplyChainUpdates": {
    "destructive": true,
    "when_to_use": "Configure a remote chain on a token pool: the remote pool addresses, the remote token address, and both rate limiter configs.",
    "preconditions": "The executing account owns the pool. Every remote address is already chain-family encoded (EVM: abi.encode(address); SVM: raw 32 bytes).",
    "postconditions": "The chain's entry on the pool matches the payload exactly.",
    "failure_modes": "REPLACE, NOT MERGE: re-applying an already-configured chain removes its whole entry first, including every registered remote pool and both rate limiter configs, so anything the payload omits is lost. Mid-migration that drops the old remote pool a lane still needs (in-flight messages then fail InvalidSourcePoolAddress) or un-throttles a lane throttled on purpose. Repeating a selector inside one payload reverts NonExistentChain, because the first removal already took it out.",
    "inputs": {
      "OUTBOUND_RATE_LIMIT_CAPACITY": "uint128 token-bucket capacity. Per direction the inputs are all-or-nothing: an enabled bucket needs CAPACITY and RATE together, and a partial set is refused naming the missing variable.",
      "OUTBOUND_RATE_LIMIT_RATE": "uint128 token-bucket refill rate. An enabled bucket needs CAPACITY and RATE together.",
      "OUTBOUND_RATE_LIMIT_ENABLED": "true/false; defaults to true when CAPACITY or RATE are set. false stands alone as a disable.",
      "INBOUND_RATE_LIMIT_CAPACITY": "uint128 token-bucket capacity (inbound). Same all-or-nothing rule per direction.",
      "INBOUND_RATE_LIMIT_RATE": "uint128 token-bucket refill rate (inbound).",
      "INBOUND_RATE_LIMIT_ENABLED": "true/false; defaults to true when CAPACITY or RATE are set. false stands alone as a disable."
    }
  },
  "ClaimAndAcceptAdmin": {
    "when_to_use": "Register a token you control in the TokenAdminRegistry in one atomic step. Prefer this over separate ClaimAdmin then AcceptAdminRole when you want a single Safe batch: AcceptAdminRole on its own preflight-requires the pending administrator to already be set, so the two standalone steps cannot be deferred into one batch, whereas this pair executes together.",
    "preconditions": "The executing account must be resolvable as the token's admin through one of the three claim paths, auto-detected in precedence: getCCIPAdmin(), then owner(), then AccessControl DEFAULT_ADMIN_ROLE.",
    "postconditions": "The TokenAdminRegistry administrator for the token is the executing account.",
    "example": "CCIP_ADMIN_ADDRESS=0xYourAdmin forge script script/setup/ClaimAndAcceptAdmin.s.sol --rpc-url $ETHEREUM_SEPOLIA_RPC_URL --account $KEYSTORE_NAME --broadcast",
    "failure_modes": "Reverts if no claim path resolves the executing account as the token admin, or if the token is already registered to a different administrator."
  },
  "SetDynamicConfig": {
    "inputs": {
      "ROUTER": "Optional. Unset preserves the pool's current on-chain router verbatim.",
      "RATE_LIMIT_ADMIN": "Optional. Unset preserves the current on-chain value verbatim, address(0) included.",
      "FEE_ADMIN": "Optional. Unset preserves the current value verbatim; an explicit address(0) restricts fee withdrawal to the owner."
    }
  },
  "UpdateRateLimiters": {
    "inputs": {
      "OUTBOUND_RATE_LIMIT_CAPACITY": "uint128 token-bucket capacity. Per direction the inputs are all-or-nothing: an enabled bucket needs CAPACITY and RATE together, and a partial set is refused naming the missing variable.",
      "OUTBOUND_RATE_LIMIT_RATE": "uint128 token-bucket refill rate. An enabled bucket needs CAPACITY and RATE together.",
      "OUTBOUND_RATE_LIMIT_ENABLED": "true/false; defaults to true when CAPACITY or RATE are set. false stands alone as a disable.",
      "INBOUND_RATE_LIMIT_CAPACITY": "uint128 token-bucket capacity (inbound). Same all-or-nothing rule per direction.",
      "INBOUND_RATE_LIMIT_RATE": "uint128 token-bucket refill rate (inbound).",
      "INBOUND_RATE_LIMIT_ENABLED": "true/false; defaults to true when CAPACITY or RATE are set. false stands alone as a disable."
    }
  },
  "SetFinalityConfig": {
    "inputs": {
      "OUTBOUND_RATE_LIMIT_CAPACITY": "uint128 token-bucket capacity. Per direction the inputs are all-or-nothing: an enabled bucket needs CAPACITY and RATE together, and a partial set is refused naming the missing variable.",
      "OUTBOUND_RATE_LIMIT_RATE": "uint128 token-bucket refill rate. An enabled bucket needs CAPACITY and RATE together.",
      "OUTBOUND_RATE_LIMIT_ENABLED": "true/false; defaults to true when CAPACITY or RATE are set. false stands alone as a disable.",
      "INBOUND_RATE_LIMIT_CAPACITY": "uint128 token-bucket capacity (inbound). Same all-or-nothing rule per direction.",
      "INBOUND_RATE_LIMIT_RATE": "uint128 token-bucket refill rate (inbound).",
      "INBOUND_RATE_LIMIT_ENABLED": "true/false; defaults to true when CAPACITY or RATE are set. false stands alone as a disable."
    }
  },
  "SetPolicyEngine": {
    "destructive": true,
    "when_to_use": "Connect an AdvancedPoolHooks contract to an ACE Policy Engine on the same chain, or disconnect the engine with the zero address. The hook calls attach() on the new engine, which starts ACE target detection.",
    "preconditions": "The executing account is the hooks owner (MODE=safe when a Safe owns it). The engine is deployed on the same chain and already provisioned for this hooks address: extractor, policies, and setTargetDefaultPolicyAllow. Every lane into this chain quotes a destGasOverhead that covers postflightCheck (UpdateTokenTransferFeeConfig).",
    "postconditions": "getPolicyEngine returns the new engine. Run make snapshot-chain: hooks.policyEngine is a governance-critical roles{} field and the old declaration fails roles-check until re-snapshotted.",
    "failure_modes": "DESTRUCTIVE: the zero address turns compliance checks off, and an unprovisioned engine rejects every transfer (PolicyRunRejected). An engine address with no code and a same-address update are refused before broadcasting. Reverts PolicyEngineDetachReverted when the old engine's detach() reverts; rerun with ALLOW_FAILED_DETACH=true. Pointing back at an engine left behind that way reverts TargetAlreadyAttached. Too little destGasOverhead fails inbound messages with TokenHandlingError(token, 0x).",
    "inputs": {
      "POLICY_ENGINE": "Address of the ACE Policy Engine on the same chain, or the zero address to disconnect the engine and stop policy checks.",
      "POOL_HOOKS": "Address of the AdvancedPoolHooks contract. Resolves via the standard ladder: inline alias > {CHAIN}_POOL_HOOKS env > registry active.poolHooks.",
      "ALLOW_FAILED_DETACH": "true calls setPolicyEngineAllowFailedDetach, tolerating a reverting detach() on the old engine (default false)."
    }
  },
  "GetPolicyEngine": {
    "when_to_use": "Read which ACE Policy Engine an AdvancedPoolHooks contract points at, or confirm none is set (policy checks disabled).",
    "inputs": {
      "POOL_HOOKS": "Address of the AdvancedPoolHooks contract. Resolves via the standard ladder: inline alias > {CHAIN}_POOL_HOOKS env > registry active.poolHooks."
    }
  }
}