Skip to content

docs: add missing storage interface declarations#799

Open
wischli wants to merge 5 commits intomainfrom
docs_add-storage-interface-abi
Open

docs: add missing storage interface declarations#799
wischli wants to merge 5 commits intomainfrom
docs_add-storage-interface-abi

Conversation

@wischli
Copy link
Contributor

@wischli wischli commented Feb 26, 2026

Product requirements

  • Interface files throughout src/ were missing declarations for public state variable getters and explicit view/pure functions that exist on the implementing contracts
  • Add all missing view/pure function declarations to their corresponding interfaces so that callers can interact with the protocol entirely through interfaces.

Design notes

  • ~143 function declarations were added across 37 interface files
  • Return types for struct-valued mappings use the flattened auto-generated getter signature (individual fields), not the struct type, to match what Solidity actually exposes.
  • Adding functions to IBatchRequestManager changed its ERC-165 interface ID from 0xaf00afbd to 0x5cdb8e3c
  • New imports were added to interface files where the return types reference other interfaces (e.g., IRoot, IHub, IGateway).

Intentionally excluded (reviewers: speak up if you disagree)

  • Implementation constants (~14): BATCH_LOCATORS_SLOT(), GLOBAL_POOL() (x3), MAINNET_CENTRIFUGE_ID(), BASE_COST(), RECOVERY_TOKEN_EXTRA_COST(), DEFAULT_SUPPORTED_TX_LIMIT(), RECEIVE_COST() (x4), FREEZE_BIT(). These are internal tuning knobs and sentinel values that integrators should not depend on. They can change between versions without notice and exposing them in interfaces suggests they are part of the contract's public API.
  • Transient storage getters (2): debited() and credited() on IAccounting. These are uint128 public transient variables that always return 0 when read externally (transient storage is cleared after each transaction). Declaring them in the interface would mislead integrators into thinking they carry meaningful state.
  • Factory-specific getters: IVaultFactory is shared across AsyncVaultFactory and SyncDepositVaultFactory. Factory-specific public variables like asyncRequestManager() or syncDepositManager() were not added to avoid breaking the shared interface.
  • RecoveryAdapter: Has no dedicated interface and one is not being created as part of this change.

@wischli wischli self-assigned this Feb 26, 2026
@lemunozm
Copy link
Contributor

Adding functions to IBatchRequestManager changed its ERC-165 interface ID from 0xaf00afbd to 0x5cdb8e3c

Thanks for pointing this. I understand the same happens for other interfaces that already support the interfaceId, but should not be an error for integrators. Our methods that check the interfaceId are already compiled.

Transient storage getters (2): debited() and credited() on IAccounting. These are uint128 public transient variables that always return 0 when read externally (transient storage is cleared after each transaction). Declaring them in the interface would mislead integrators into thinking they carry meaningful state.

I think that could not be fully true, from a hook, you could read those values != 0 inside of a transaction.

RecoveryAdapter: Has no dedicated interface and one is not being created as part of this change.

Also good point. Not sure if adding an inheritance in the contract to a possible new interface modifies the bytecode, maybe not, and this can be added. Although this contract will never be used directly by externals

@lemunozm
Copy link
Contributor

To avoid the Tag Env CI issue, I think we just need to set in the pharos env the commit 0931a54f(from the tag deploy-mainnet-v3.1-0931a54 that was already created in deploy-v3.1.0 branch). Basically I think the correct commit added in env/pharos.json as deploy commit is not ok.

@github-actions
Copy link

github-actions bot commented Mar 3, 2026

Coverage after merging docs_add-storage-interface-abi into main will be

97.24%

Coverage Report
FileStmtsBranchesFuncsLinesUncovered Lines
src/adapters
   AxelarAdapter.sol97.67%90%100%100%118
   ChainlinkAdapter.sol98.11%91.67%100%100%95
   LayerZeroAdapter.sol98.41%90%100%100%124
   RecoveryAdapter.sol100%100%100%100%
   WormholeAdapter.sol97.67%90%100%100%108
src/admin
   OpsGuardian.sol100%100%100%100%
   ProtocolGuardian.sol100%100%100%100%
   Root.sol100%100%100%100%
   TokenRecoverer.sol100%100%100%100%
src/core/hub
   Accounting.sol94.79%88%100%96.61%132, 134, 137, 141, 144
   Holdings.sol97.71%88.89%100%100%118, 243, 82
   Hub.sol93.98%81.13%93.02%97.54%269, 287, 305, 339, 343, 374–375, 413, 498–499, 544, 549, 586, 601, 87
   HubHandler.sol98%90.91%100%100%71
   HubRegistry.sol92.39%76.67%100%100%118, 124, 130, 35, 46, 79, 99
   ShareClassManager.sol98.81%95.45%100%100%42
src/core/libraries
   PricingLib.sol100%100%100%100%
src/core/messaging
   GasService.sol96.55%100%87.50%96.20%106, 135, 145
   Gateway.sol100%100%100%100%
   MessageDispatcher.sol99.60%98.55%100%100%733
   MessageProcessor.sol82.42%60.26%100%99.01%101, 103, 109, 112, 114, 125, 130, 139, 142, 145, 157, 160, 163, 168, 178, 181, 190, 193, 196, 209, 220, 225, 228, 232, 83–84, 87–88, 91–92, 97, 99
   MultiAdapter.sol100%100%100%100%
src/core/messaging/libraries
   MessageLib.sol100%100%100%100%
src/core/spoke
   BalanceSheet.sol97.47%96.97%92.59%98.55%291, 348, 57
   PoolEscrow.sol100%100%100%100%
   ShareToken.sol92.41%60%94.44%98.04%100, 112, 144, 146, 32
   Spoke.sol97.46%89.71%100%100%132, 132–133, 133, 135, 92–93
   VaultRegistry.sol93.88%85.71%100%98.18%54, 60–62, 98–99
src/core/spoke/factories
   PoolEscrowFactory.sol100%100%100%100%
   TokenFactory.sol100%100%100%100%
src/core/utils
   BatchedMulticall.sol100%100%100%100%
   ContractUpdater.sol100%100%100%100%
src/deployment
   ActionBatchers.sol84.55%62.50%80%86.22%434, 436–437, 439, 439–440, 442, 444, 444–445, 449, 449–450, 452, 455, 455–456, 458, 461, 461–462, 465, 468, 468, 470, 472, 504–508, 513–514, 516–517, 519–520
src/hooks
   BaseTransferHook.sol100%100%100%100%
   FreelyTransferable.sol92.31%80%100%100%37
   FreezeOnly.sol100%100%100%100%
   FullRestrictions.sol95.24%88.89%100%100%47
   RedemptionRestrictions.sol85.71%50%100%100%37
src/hooks/libraries
   UpdateRestrictionMessageLib.sol90%50%100%100%40, 61, 82
src/managers/hub
   NAVManager.sol100%100%100%100%
   SimplePriceManager.sol100%100%100%100%
src/managers/spoke
   MerkleProofManager.sol97.01%87.50%100%100%103, 110
   OnOfframpManager.sol100%100%100%100%
   QueueManager.sol100%100%100%100%
src/managers/spoke/decoders
   BaseDecoder.sol100%100%100%100%
   CircleDecoder.sol83.33%100%100%75%22
   VaultDecoder.sol100%100%100%100%
src/misc
   Auth.sol100%100%100%100%
   ERC20.sol100%100%100%100%
   Escrow.sol56.25%33.33%100%66.67%17, 19, 23–24, 24, 24, 26
   Multicall.sol91.67%66.67%100%100%19
   Recoverable.sol100%100%100%100%
   ReentrancyProtection.sol90%75%100%100%24
src/misc/libraries
   ArrayLib.sol100%100%100%100%
   BitmapLib.sol100%100%100%100%
   BytesLib.sol90.27%56%100%100%109, 120, 131, 14, 142, 153, 16, 164, 175, 186, 87
   CastLib.sol95.24%66.67%100%100%10, 34
   EIP712Lib.sol100%100%100%100%
   ExcessivelySafeCallLib.sol100%100%100%100%
   MathLib.sol93.46%76.19%100%97.33%34–35, 44, 46, 48, 50, 52
   MerkleProofLib.sol100%100%100%100%
   SafeTransferLib.sol96.97%92.86%100%100%75
   SignatureLib.sol95.24%80%100%100%17
   StringLib.sol100%100%100%100%
   TransientArrayLib.sol100%100%100%100%
   TransientBytesLib.sol100%100%100%100%
   TransientStorageLib.sol100%100%100%100%
src/spell
   V2CleaningsSpell.sol0%0%0%0%100, 100, 100–102, 102, 102–104, 104–105, 108, 110–111, 113, 40–41, 41, 41–42, 44–46, 48–49, 52, 54, 54, 56, 56–59, 63, 63–64, 69, 69–73, 77–80, 82–83, 86–89, 89–92, 97–98, 98–99
src/utils
   RefundEscrow.sol100%100%100%100%
   RefundEscrowFactory.sol100%100%100%100%
   SubsidyManager.sol100%100%100%100%
src/valuations
   IdentityValuation.sol100%100%100%100%
   OracleValuation.sol100%100%100%100%
src/vaults
   AsyncRequestManager.sol96.85%86.36%100%99.64%195, 198, 201, 204, 215, 227, 295, 328, 455, 460, 505, 573, 580
   AsyncVault.sol96.25%83.33%95%98.15%146, 47
   BaseVaults.sol92.50%80.77%95.24%93.94%124, 137, 239, 309–310, 396–397, 85–86, 86, 86–88
   BatchRequestManager.sol100%100%100%100%
   SyncDepositVault.sol100%100%100%100%
   SyncManager.sol96.45%88.89%100%97.89%106–107, 109, 67, 72
   VaultRouter.sol87.37%58.82%100%91.53%107, 107, 109–110, 110, 112, 149, 70, 73–74, 86–87
src/vaults/factories
   AsyncVaultFactory.sol93.75%50%100%100%32
   SyncDepositVaultFactory.sol95%50%100%100%40
src/vaults/libraries
   RequestCallbackMessageLib.sol89.58%50%100%100%104, 139, 38, 57, 77
   RequestMessageLib.sol89.74%50%100%100%37, 55, 72, 89

Copy link
Contributor

@lemunozm lemunozm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants