Bullbit

We express our gratitude to the Bullbit team for the collaborative engagement that enabled the execution of this Smart Contract Security Assessment.

A custody bridge moves USDC and BUBI between Base and XChain. Deposits land in deterministic per-user wallets and are swept into a pooled vault; withdrawals are paid only when a whitelisted relayer submits a claim with an on-chain 2-of-3 validator attestation.

The system users should acknowledge all the risks summed up in the risks section of the report

Documentation quality

• On-chain deposit, withdraw, roles, and upgrade behaviour are described.

• Off-chain bridge requirements (mint/burn, signer, backend policy) are only partly specified.

• A technical description of architecture, storage, and deployment is provided.

Code quality

• The development environment is configured.

• Scoped contracts follow a consistent style with NatSpec and an extensive test suite.

Test coverage

Code coverage of the project is 100% (branch coverage).

• Deployment and basic user interactions are covered with tests.

• Negative cases coverage is present.

• Interactions by several users are tested thoroughly.

The architecture is split into a deposit subsystem and a withdrawal subsystem. DepositFactory and Vault are UUPS upgradeable contracts that use ERC-7201 namespaced storage, Ownable2Step ownership, Pausable, and ReentrancyGuard. Both call _disableInitializers in the implementation constructor and accept only an owner in initialize, so initialization calldata can be identical across chains and proxy addresses can be reproduced when the documented deploy path is followed. The factory vault pointer and coldVault are assigned after deployment. Ownership cannot be renounced. Owner actions, including _authorizeUpgrade, execute immediately with no timelock. DepositForwarder is a non-upgradeable ERC-20 wallet. Instances are deployed with CREATE2 from the frozen ForwarderInitcode CREATION_CODE and the factory proxy address. The CREATE2 salt is destRecipient. The DepositForwarder source is imported for calls and is not used as deployment bytecode. Digest supplies the withdraw hash that Vault verifies so Solidity stays aligned with the documented Go signer. Token movement uses the ERC-20 IERC20 interface and SafeERC20 transfers. Native ETH is not handled.

On the deposit path, deployWallet is limited to the operator or owner and to proxy execution via onlyProxy. The factory records isChild and walletToDestRecipient. The owner configures setVault and setSupportedToken. While the factory is unpaused and a vault is set, sweep is permissionless: a registered child, a whitelisted token, and a non-zero forwarder balance are required. forward then transfers the full IERC20 balance to the vault, and Swept records the vault balance delta. sweepMany skips members with a zero token balance, invokes sweep through try/catch, and emits SweepSkipped when a member fails. rescue lets the operator or owner move a non-whitelisted token out of a child to a non-zero to. pause may be invoked by the operator or owner. unpause is owner-only. Pause applies to sweep and sweepMany only.

On the withdrawal path, Vault holds pooled IERC20 inventory and pays releaseWithAttestation. The caller must be a releaseRelayer. Claim chainId must equal block.chainid. Signatures are recovered with ecrecover over Digest digestOf (domain, chain id, vault proxy, request id, token, recipient, amount). Recovered addresses must be strictly increasing. Accumulated member power must meet powerThreshold. An unset valset (powerThreshold of zero) reverts with InsufficientPower. setValset is owner-only and enforces a non-empty set of at most 100 members, unique non-zero attestors and powers, a threshold in [ceil(2 * sum / 3), sum], and no member that can meet the threshold alone. The signature array is capped at 100. The requestId is written to released before safeTransfer. A zero recipient finalizes the claim without a transfer. A duplicate requestId emits ReleaseSkipped and returns. No on-chain amount caps, screening, or rate limits are implemented. Releases may be paused by the operator or owner, and tokens may be consolidated to coldVault. consolidate remains available while paused. The owner sets coldVault, the valset, relayers, and the operator.

Files in Scope

• Vault.sol: Pooled ERC-20 custody hub that pays withdrawal claims. releaseWithAttestation accepts a relayer-submitted claim and a power-weighted attestation. setValset replaces the attestor set. consolidate sends tokens to the owner-set coldVault. pause and unpause are asymmetric. The owner configures operator, relayers, and cold vault and authorizes UUPS upgrades.

• DepositFactory.sol: CREATE2 factory for per-user DepositForwarder wallets and the sweep path into Vault. deployWallet materializes a child. sweep and sweepMany are permissionless consolidation entry points. rescue extracts non-whitelisted tokens. The owner sets the vault and supported tokens and authorizes UUPS upgrades. pause blocks sweeps only.

• DepositForwarder.sol: Minimal per-user ERC-20 receiver with an immutable FACTORY. forward transfers the full token balance to a non-zero destination and reverts unless called by the factory.

• Digest.sol: Library that is the single source for the withdraw digest used by Vault. digestOf returns keccak256 of abi.encode over DOMAIN_WITHDRAW, chain id, vault address, request id, token, recipient, and amount.

• ForwarderInitcode.sol: Library that stores frozen DepositForwarder creation bytecode in CREATION_CODE. DepositFactory uses this literal in computeAddress and deployWallet so deposit addresses remain stable across factory implementation upgrades.

Privileged roles

Vaultsol

• owner (inherited from Ownable2StepUpgradeable): Validator set, release relayers, operator, cold vault, pause lift, UUPS upgrades, and ownership transfer are controlled. All operator actions are available to this role.

• • Can call setValset to replace the full attestor set and power threshold.

  • Can call setReleaseRelayer to grant or revoke release relayer status.

  • Can call updateOperator to set the operator, or to clear it with the zero address so that operator functions remain available only to the owner.

  • Can call setColdVault to set the cold vault destination used by consolidate.

  • Can call unpause to resume releaseWithAttestation.

  • Can call consolidate to transfer tokens from the vault to the cold vault. This remains available while paused.

  • Can call pause to halt releaseWithAttestation.

  • Can call transferOwnership to nominate a pendingOwner, or to cancel a pending transfer by nominating the zero address.

  • Can call upgradeToAndCall (inherited from UUPSUpgradeable, authorized by _authorizeUpgrade) to replace the proxy implementation.

  • Can call renounceOwnership, which always reverts. Ownership cannot be removed.

• operator: Releases can be paused and tokens can be moved to the cold vault.

• • Can call consolidate to transfer tokens from the vault to the cold vault. This remains available while paused.

  • Can call pause to halt releaseWithAttestation.

• release relayer: Attested withdraw claims can be submitted for payout.

• • Can call releaseWithAttestation while not paused to mark a claim released and transfer tokens to the claim recipient, or to complete a claim without a transfer when the recipient is the zero address.

• attestor: Withdraw claims are authorized by ECDSA signatures counted toward the power threshold.

• • Can authorize releaseWithAttestation by signing the withdraw digest. Release succeeds only when accumulated attestor power meets powerThreshold.

• pendingOwner (inherited from Ownable2StepUpgradeable): A pending ownership transfer can be completed.

• • Can call acceptOwnership to become the owner.

DepositFactorysol

• owner (inherited from Ownable2StepUpgradeable): Vault address, supported tokens, operator, pause lift, UUPS upgrades, and ownership transfer are controlled. All operator actions are available to this role.

• • Can call setVault to set the Vault address that receives swept deposits.

  • Can call setSupportedToken to add or remove a token from the sweep whitelist.

  • Can call updateOperator to set the operator, or to clear it with the zero address so that operator functions remain available only to the owner.

  • Can call unpause to resume sweep and sweepMany.

  • Can call deployWallet (gated by onlyProxy) to deploy a DepositForwarder via CREATE2, record the destination recipient, and mark the address as a child.

  • Can call rescue to forward a token that is not on the supported whitelist from a child DepositForwarder to a chosen recipient.

  • Can call pause to halt sweep and sweepMany.

  • Can call transferOwnership to nominate a pendingOwner, or to cancel a pending transfer by nominating the zero address.

  • Can call upgradeToAndCall (inherited from UUPSUpgradeable, authorized by _authorizeUpgrade) to replace the proxy implementation.

  • Can call renounceOwnership, which always reverts. Ownership cannot be removed.

• operator: Forwarders can be deployed, unsupported tokens can be rescued, and sweeps can be paused.

• • Can call deployWallet (gated by onlyProxy) to deploy a DepositForwarder via CREATE2, record the destination recipient, and mark the address as a child.

  • Can call rescue to forward a token that is not on the supported whitelist from a child DepositForwarder to a chosen recipient.

  • Can call pause to halt sweep and sweepMany.

• pendingOwner (inherited from Ownable2StepUpgradeable): A pending ownership transfer can be completed.

• • Can call acceptOwnership to become the owner.

• anyone: Supported-token balances can be swept from registered children while the factory is unpaused.

• • Can call sweep while not paused to forward a supported token's full child balance to the configured vault and emit Swept with the vault balance delta.

  • Can call sweepMany while not paused to iterate a caller-supplied forwarder list, skip zero balances, and isolate per-member sweep failures with SweepSkipped.

DepositForwardersol

• FACTORY: The full ERC20 balance of a token can be transferred to a destination.

• • Can call forward to transfer the entire ERC20 balance of a token to a destination that is not the zero address.

The scope of the project includes the following smart contracts from the provided repository:

Assets in Scope