[Feature] Implement real rate sources for the migration keeper

[collinsezedike]

Summary

The migration keeper added in #469 (packages/stellar-sdk-helpers/src/migration-keeper.ts) compares rates across a vault's candidate protocol adapters and calls migrate_adapter when a candidate clears a configured improvement threshold. Rate comparison is deliberately pluggable via a RateSourceFn, and the shipped default always returns null ("rate unknown"), so the keeper currently never migrates anything. This issue is the actual rate-source implementation that default is standing in for.

Motivation

Without a real rate source, the migration keeper is inert: it has the full mechanism (discovery, threshold check, slippage-bounded migrate_adapter call, retry and deadline handling, structured failure reporting) but no way to decide when a migration is actually warranted. This is the last piece needed for the vault to genuinely auto-route to the best available yield, the core value proposition #469 exists for.

Proposed Solution

Neither adapter contract exposes a ready-made comparable rate today:

• BlendAdapter (packages/contracts/blend-adapter/src/lib.rs) exposes total_assets() (a point-in-time USDC value) and, via get_pool(), the underlying pool's raw Reserve data: utilization (data.b_supply/d_supply), and the kinked-curve parameters r_base/r_one/r_two/r_three/util/max_util/reactivity. A real rate source needs to reimplement Blend's three-slope interest rate formula off-chain from these inputs.
• DefindexAdapter exposes get_asset_amounts_per_shares(), a share-price snapshot. Deriving an annualized rate needs a second sample over time; there's no history stored anywhere for this today, this likely needs either a persistence layer (out of scope for a stateless keeper as currently designed) or a different approach, e.g. reading DeFindex's own reported strategy APY if it exposes one.

Implement RateSourceFn (the type is already defined in migration-keeper.ts) for both protocols and wire it into runMigrationKeeper's default, replacing the always-null stub.

Scope

Field	Value
Area	SDK
Protocol affected	Both
Network	testnet
Breaking change?	No (fills in an existing pluggable seam, no signature changes)

Alternatives Considered

Leaving the default as-is indefinitely: safe (the keeper simply never migrates), but means #469's actual stated goal, automatic yield routing, never happens in practice regardless of how the rest of the mechanism is tested.

Acceptance Criteria

• Blend rate source correctly computes the current supply rate from Reserve data, verified against Blend's own real testnet reserve behavior, not just internal consistency
• DeFindex rate source produces a comparable annualized rate, with an explicit answer to where the time-series sample lives (or an alternative approach if DeFindex exposes a usable rate directly)
• Both are wired in as runMigrationKeeper's default RateSourceFn, replacing the always-null stub
• The migration keeper genuinely triggers a migrate_adapter call under real conditions (verified on testnet, not just against injected fakes in unit tests), this is the acceptance bar for [Feature] Automatic protocol-yield routing via migrate_adapter keeper #469 itself being functionally done, not just this issue
• Existing migration keeper test suite still passes; new tests cover the rate formulas themselves against known inputs/outputs

[OpadijoIdris]

can i work on this issue?

[collinsezedike]

Update from reviewing #512: the mechanism around `RateSourceFn` got hardened since this issue was filed, worth knowing before implementing the actual formulas.

• Candidate evaluation (`resolveCandidatePool` + `rateSource` per candidate) is now retried with the same backoff/deadline-budget policy as discovery and submission, and a failure is now attributed to the actual candidate adapter/protocol being evaluated, not the vault's current one. Previously neither was true. Nothing left to do here before wiring in a real rate source.
• Worth designing the real rate source to reuse `DiscoveredVault.currentAdapterId`/`currentPoolId` (already fetched during discovery) rather than re-querying them, see the note already in `migration-keeper.ts`.
• Separately, the deployed `MeridianDefindexAdapter` address (`CAJVTA7EC3ZL3G4WSU4QIRB7RU7SUFUUJDEB7JE6CQQNPE7QC5OBSAM6`) is the one contract address in the system with no bytecode-verification CI gate, deliberately kept out of `constants.ts` to avoid tripping the already-broken vault check ([Bug] Live testnet vault predates migrate_adapter, needs redeployment #514). Once this issue and [Bug] Live testnet vault predates migrate_adapter, needs redeployment #514 both land and this adapter is a real migration target, that gap is worth closing, likely by generalizing `verify-contract-addresses.yml` to cover a second category of addresses independently of the vault-address check.

[collinsezedike]

One more scoping gap from reviewing #512's third round: config.candidateAdapters (from MERIDIAN_ADAPTER_<PROTOCOL>_ID) is a single global map applied identically to every discovered Meridian vault, not scoped per vault. The deployed MeridianDefindexAdapter is initialized against one specific vault address; if a second Meridian vault is added to KNOWN_POOLS later (e.g. a EURC vault), the keeper would try to migrate_adapter it to the same DeFindex adapter address, which was never initialized for that vault, an on-chain auth failure, not caught anywhere in migration-keeper.ts today.

Not a live bug (exactly one Meridian vault exists), but worth designing for when this issue's rate-source work lands, since that's also when a second vault becomes more likely to matter. Candidate config probably needs to become per-vault-scoped (e.g. MERIDIAN_ADAPTER_<VAULT>_<PROTOCOL>_ID or similar) rather than global, at the same time.

[collinsezedike]

@OpadijoIdris can you accommodate the new scope for this issue?