feat(sdk-core): pre-flight balance check for depositToVault

[bitgo-ai-agent-dev]

Summary

• Adds InsufficientBalanceError (structured error with assetToken, available, requested fields) to defiVault.ts and exports it from the defi module index.
• Adds assertSufficientAssetBalance private method that fetches a fresh wallet snapshot (?allTokens=true) and compares the spendable balance of the vault's assetToken against params.amount using BigNumber.
• depositToVault calls this check after fetching vault config, before dispatching to depositToConcreteVault or depositToMorphoVault.

Decision log

1. Where to place the balance check

• defiVault.ts:102 — depositToVault is the single entrypoint for all deposit paths.
• Options: (A) In depositToVault before dispatch — covers both Concrete and Morpho uniformly; (B) Duplicated in each private path; (C) Caller's responsibility.
• Chose A: single check, DRY, applies to all paths.

2. Balance source: stale _wallet vs. fresh API call

• _wallet.spendableBalanceString may be stale (wallet constructed before deposit call).
• Options: (A) Fetch fresh via GET /wallet/{id}?allTokens=true; (B) Use cached _wallet data.
• Chose A: fresh fetch guarantees correctness. ?allTokens=true ensures ERC-20 token balances are included.

3. Token lookup: assetToken === walletCoin vs. tokens array

• For Concrete BTC: vault assetToken is 'btc' which matches vault coin 'btc' — use top-level spendableBalanceString.
• For Morpho: vault assetToken is e.g. 'usdc', vault coin is 'eth' — search the tokens array by tokenName.
• Missing token entry → balance treated as '0' → throws InsufficientBalanceError.

4. BigNumber for comparison

• Used BigNumber (already a dep of sdk-core) to avoid float precision issues on base-unit integer strings. Never floats for monetary amounts.

5. Test structure

• depositToVault now makes two GET requests: vault config + wallet balance.
• Updated all existing tests to use onFirstCall()/onSecondCall() on mockBitGo.get.
• Fixed mockBaseCoin.url stub to return a real URL so wallet.url() works.

Test evidence

New tests added (5 total):

• concrete_btccx: throws InsufficientBalanceError when native coin balance is too low
• concrete_btccx: does not throw when balance exactly equals requested amount
• morpho: throws InsufficientBalanceError when token balance is too low
• morpho: throws InsufficientBalanceError when token is absent from wallet (balance treated as 0)
• morpho: does not throw when balance exactly equals requested amount

39 passing (81ms)
1 pending

Lint: ✅ TypeCheck: ✅ Full suite: ✅ (478 passing)

Open questions

None.

Out of scope

• resumeDeposit — no balance check needed; the approve txRequest is already created at this point.
• withdrawFromVault balance check (receipt/share token) is tracked in sibling ticket DEFI-372.

🤖 Generated with Ralph

[linear-code]

DEFI-371

[bitgo-ai-agent-dev]

@claude please review this PR

[davidkaplanbitgo]

Change the code owners so that this does not require a BTC team review