Skip to content

Failed Deposit Troubleshooting

Failed deposits should be diagnosed by control plane: permissioning, custody route, economic readiness, governance policy, then deposit-root mechanics.

Fast Triage Table

Symptom or revert Layer Immediate check
DepositIntentNotAllowlisted Permissioning Recompute intent with pubkey, credentials, amount, caller, and current allowlistEpoch.
DepositIntentAlreadyConsumed Replay protection Confirm whether this exact tuple was already used; do not re-add consumed intent.
InvalidAuthorizedDepositor Permissioning authorizedDepositor cannot be zero.
InvalidAllowedDepositAmount Permissioning Amount must be at least MIN_DEPOSIT_AMOUNT_GWEI.
Phase1DepositMustBeExactly32CTN Phase-1 policy Phase-1 custody path requires exactly 32_000_000_000 gwei.
WithdrawalCredentialsMustBeExecutionAddress Custody route First credential byte must be 0x01.
NonCanonicalWithdrawalCredentials Custody route Bytes 1 through 11 must be zero.
VaultNotFactoryRegistered Custody route Address embedded in credentials is not a registered factory vault.
VaultPubkeyBindingMismatch Custody route Factory/vault pubkey hash does not match submitted pubkey.
VaultReadinessUnproven Economic safety Controller readiness is not safe for deposit.
VaultReadinessReserveProofStale Economic safety Reserve proof timestamp exceeds the max proof age.
VaultReadinessRouterBootstrapOpen Launch lock Factory treasury router still reports bootstrap open.
ImplementationNotApproved or policy mismatch Governance Live implementation or code hash is not accepted by the governor registry.
DepositDataRootMismatch Deposit mechanics Recompute deposit-data root from exact submitted fields.

Diagnostic Procedure

  1. Decode the revert selector and map it to the table above.
  2. Recompute the intent hash using the current allowlistEpoch and actual transaction sender.
  3. Check allowedDeposits[intentHash] and consumedIntents[intentHash].
  4. Decode the vault address from withdrawal credentials and verify factory isVault plus vaultByValidatorPubkeyHash.
  5. Compare vault metadata: pubkey hash, credentials, config hash, derivation version, controller, and exit-request contract.
  6. Query controller depositReadiness(vault) and inspect schema versions, policy version, trigger, reserve coverage, beneficiary initialization, risk state, claim state, and freshness.
  7. Re-run governor assertions for deposit proxy, controller proxy, factory proxy, gatekeeper proxy, and vault beacon.
  8. Recompute deposit_data_root.
  9. If the failure follows any governance event, open a suspicious-governance investigation before retrying.

Escalation

Escalate to governance/security if:

  • any live implementation policy assertion fails;
  • beacon authority differs from the baseline upgrade governor;
  • controller readiness regresses unexpectedly;
  • treasury router bootstrap reopens;
  • an intent exists for an unexpected depositor;
  • the same pubkey appears to have multiple vault candidates.