Dampen repeated failed SDK queries

[Seranged]

Summary

• Add a short failure TTL to the SDK default query cache so repeated identical failed queries rethrow locally instead of hammering the underlying transport.
• Document the new failureTtlMs cache option and the current V3 vault resolve path.

Changes

• Extend QueryCacheConfig with failureTtlMs, defaulting to 5 seconds alongside the existing success TTL.
• Preserve the old immediate-retry behavior when consumers set failureTtlMs: 0.
• Cover cached failures, opt-out behavior, and cooldown expiry in the read-path infrastructure test.

Context

• Lite has an app-side mitigation in Reduce V3 proxy retry amplification euler-lite#652.
• This SDK follow-up gives other SDK consumers the same basic thundering-herd protection when V3 or other external reads degrade.

Test plan

• pnpm --filter @eulerxyz/euler-v2-sdk test -- readPathInfra.test.ts
• pnpm --filter @eulerxyz/euler-v2-sdk typecheck
• pnpm --filter @eulerxyz/euler-v2-sdk build
• pnpm --filter @eulerxyz/euler-v2-sdk lint (exits 0; reports existing unrelated warnings in src/utils/irm.ts, src/utils/oracle.ts, and src/utils/stateOverrides/*)

[LeonardEulerXYZ]

Leonard review — approved

Reviewed current head c4a7670159d98c022c0c0224c61218ea62f09999 for euler-xyz/euler-sdks PR #68.

Walkthrough

• Adds failureTtlMs to the built-in QueryCacheConfig and default query cache implementation.
• Failed decorated query* calls now rethrow from the local cache during a short cooldown instead of repeatedly hitting the underlying RPC/HTTP transport.
• failureTtlMs: 0 preserves the prior immediate-retry behavior.
• Documentation now describes the success/failure TTL split and the current V3 vault resolver path.
• Tests cover cached failures, opt-out behavior, and cooldown expiry.

Validation performed

• Inspected full diff and surrounding SDK query-cache/buildSDK context.
• Reviewed package export/type surface: QueryCacheConfig.failureTtlMs appears in built declarations after build.
• Security/supply-chain sweep: no package, lockfile, workflow, script, dependency, secret, telemetry, network-target, or executable-config changes in the PR diff.
• Scalability / maintainability hygiene pass: traced the central resolvedBuildQuery/applyBuildQuery path across services, adapters, and plugins; this is correctly implemented once in the shared query-cache abstraction rather than duplicated per V3/RPC callsite. Similar query consumers inherit the behavior through the existing decorator wiring, while custom buildQuery consumers remain intentionally out of scope.
• Active bot/reviewer feedback: no prior comments, formal reviews, or inline review comments were present to verify/refute.

Commands run locally:

• pnpm install --frozen-lockfile
• pnpm --filter @eulerxyz/euler-v2-sdk test -- readPathInfra.test.ts — passed; Vitest selected the package test suite, 26 files / 346 tests passed.
• pnpm --filter @eulerxyz/euler-v2-sdk typecheck — passed.
• pnpm --filter @eulerxyz/euler-v2-sdk build — passed.
• pnpm --filter @eulerxyz/euler-v2-sdk lint — exited 0 with existing unrelated warnings in src/utils/irm.ts, src/utils/oracle.ts, and src/utils/stateOverrides/*, matching the PR test plan.

Verdict

Approved. I did not find blocking correctness, SDK API compatibility, generated-package, dependency, build, type-safety, protocol-integration, security, or downstream consumer risks.

Comment lifecycle: no prior Leonard walkthrough, formal review, or inline comments found; no cleanup needed.

Screenshots: not applicable — this PR changes SDK cache behavior and docs, not a user-visible UI.