Skip to content

Vault Creation Flow

sequenceDiagram
    participant Owner
    participant Factory
    participant Beacon
    participant Vault
    participant Controller

    Owner->>Factory: deployVault(pubkey,beneficiary,...)
    Factory-->>Factory: validate credential type and maxEffectiveBalance
    Factory-->>Factory: derive pubkey hash and CREATE2 salt
    Factory->>Vault: deploy CenturionBeaconProxy(vaultBeacon, initData)
    Factory->>Controller: initializeSeat(vault,...)
    Factory-->>Owner: emit VaultDeployed

Invariants

  • one vault per validator pubkey hash
  • vault deployment uses beacon proxy runtime
  • controller seat is initialized immediately after vault deployment
  • credential type for admission is constrained to Execution01

Operational Checks

Before allowing a deposit, verify vaultByValidatorPubkeyHash, isVault, the vault beacon, vault runtime code hash, controller, exit-request contract, and computed execution withdrawal credentials. The deposit contract redoes these checks, but operations should catch mistakes before the user-facing transaction fails.

Failure Modes

Vault deployment can fail or become unusable if the pubkey length is wrong, the pubkey hash already has a vault, the beacon authority is wrong, maxEffectiveBalanceWei is not the standard maximum, beneficiary is invalid, or controller seat initialization rejects parameters.

Evidence To Archive

VaultDeployed, controller SeatInitialized, previewed vault address, withdrawal credentials, factory mapping readback, and controller seat/readiness snapshots.

Source-Grounded Operating Model

Purpose

This page exists to show how a validator-specific custody route is created before any deposit can be admitted. Treat it as an operating model, not as proof that any deployed address is already correct. Deployed-state evidence is still Evidence required unless archived separately.

Actors

factory owner, deployment reviewer, controller owner, vault beneficiary, backend/oracle engineer, auditor.

Contracts Involved

CenturionVaultFactory, CenturionBeaconProxy, CenturionWithdrawalVault, CenturionEconomicController, and the vault beacon.

Step-By-Step Flow

  1. factory owner submits a 48-byte validator pubkey and beneficiary/destination configuration.
  2. factory derives the pubkey hash and deterministic vault metadata.
  3. a beacon proxy vault is deployed and initialized with controller, exit route, pubkey, and credentials.
  4. factory records isVault and vaultByValidatorPubkeyHash.
  5. controller initializes the seat and associated economic limits.
  6. operators verify the previewed execution withdrawal credentials before admission.

Failure Modes

  • duplicate pubkey hash.
  • wrong beneficiary or destination.
  • wrong beacon authority.
  • controller seat not initialized.
  • credential preview mismatch.

Fail-Closed Behavior

The handbook treats missing, stale, mismatched, or contradictory evidence as a stop condition. Onchain paths generally revert, cancel pending claims, or leave queued operations unexecuted rather than accepting a weaker proof. Operators should preserve the revert reason or event trail before retrying.

Operator Implications

  • Do not substitute Upgrade governance evidence for Deposit permissioning evidence.
  • Do not substitute Deposit permissioning evidence for Custody/readiness evidence.
  • Do not substitute Custody/readiness evidence for Economic/claim safety evidence.
  • Archive the source snapshot, transaction hashes, event logs, and reviewer approvals that correspond to the specific operation.

Source References

CenturionVaultFactory.deployVault, CenturionWithdrawalVault.initialize, CenturionEconomicController.initializeSeat, previewExecutionWithdrawalCredentials.