Skip to content
This repository was archived by the owner on May 26, 2026. It is now read-only.

Add contract reference docs for Teller, BoringQueue, BoringVault, and Accountant#1

Open
gitshreevatsa wants to merge 2 commits into
Veda-Labs:mainfrom
gitshreevatsa:add-integration-contracts-docs
Open

Add contract reference docs for Teller, BoringQueue, BoringVault, and Accountant#1
gitshreevatsa wants to merge 2 commits into
Veda-Labs:mainfrom
gitshreevatsa:add-integration-contracts-docs

Conversation

@gitshreevatsa
Copy link
Copy Markdown

Adds four contract reference documents under public-docs/integrations/contracts/. These cover the four core contracts an integrator touches when building on top of the BoringVault system.

What's included

Each doc is structured in three layers: a quick overview for orientation, a working integration guide with step-by-step flows and a runnable viem example, and a full function reference with parameters, return values, events, revert conditions, and internal behavior notes.

  • Teller.md - deposit and withdrawal entry point; covers ERC20 and native ETH flows, share lock mechanics, the deposit cap, deny lists, and refundDeposit
  • BoringQueue.md - async withdrawal queue; covers the request lifecycle, discount model, solver callback flow, and withdrawCapacity management
  • BoringVault.md - custody contract and share token; covers enter/exit, manage, and the beforeTransfer hook
  • Accountant.md - exchange rate oracle and fee ledger; covers rate reading, multi-asset pricing via rate providers, fee mechanics, and auto-pause behavior

Non-obvious behavior documented

A few things in the contracts will cause integration failures without prior warning, so these are called out explicitly:

  • deposit and withdraw carry requiresAuth - the deployed Authority must be configured to allow public access, or all user calls silently revert
  • isPaused blocks both deposits and withdrawals, not just deposits as the source comments suggest
  • bulkDeposit skips the share lock and writes no refund history - shares are immediately transferable and non-refundable
  • Approval target for deposits is the vault, not the Teller
  • Approval target for BoringQueue withdrawals is the BoringQueue, not the vault or Teller
  • withdrawCapacity is not restored when a solver fills requests - only cancellations restore it, so admins need to replenish it manually after each solve batch
  • amountOfAssets on a queue request is fixed at submission time - exchange rate increases after submission do not benefit the user
  • claimFees can only be called by the vault itself, not by an admin EOA directly; the path is vault.manage(accountant, abi.encodeWithSelector(claimFees.selector, asset), 0)
  • updateExchangeRate does not validate newExchangeRate > 0; keepers need to guard this off-chain
  • setRateProviderData does not validate the provider returns a nonzero rate; a broken provider causes all deposits and withdrawals for that asset to revert

How the docs were generated

All docs were written from the actual Solidity source (TellerWithMultiAssetSupport.sol, BoringOnChainQueue.sol, BoringVault.sol, AccountantWithRateProviders.sol). No functions, parameters, or behaviors were invented.

@gitshreevatsa
Copy link
Copy Markdown
Author

Also opened a PR on the boring-vault repo with a TypeScript SDK if that's useful context — same exploration, different output.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant