feat: per-request network override + 12 clause-builder intent tools

[davidecarpini]

Summary

Make the MCP server per-request network aware and add 12 new build*Clauses intent tools so external agent loops (e.g. veworld-b3mo-backend) can stop carrying ABIs and clause encoding locally and delegate everything to this server.

This is a breaking change (bumped to 2.0.0-alpha.0):

• every tool input shape now exposes an optional network field
• new public tool surface: getStargateLevels, resolveVnsName, resolveToken, getCuratedStargateValidators, plus 12 build*Clauses tools

Per-request network awareness (Fase 1)

• services/thor/request-context.ts — runWithRequestNetwork + getRequestNetwork backed by AsyncLocalStorage
• services/thor/config.ts — replaces the singleton ThorClient with a Map<ThorNetworkType, ThorClient> cache; getThorClient / getThorNetworkType / getThorNodeUrl now resolve in order: explicit override → request context → env default
• server.ts — every registered tool gets network injected into its input shape and runs inside runWithRequestNetwork(network), so existing tools keep working with the env default while clients that pass network get a per-request override (no leak across concurrent requests, see parity tests)

Registry primitives (Fase 2)

• contracts-registry/addresses.ts — add vechainSwapRouter, wvet, vtho for mainnet/testnet
• contracts-registry/abis.ts — add UNISWAP_V2_ROUTER_ABI
• contracts-registry/index.ts — new swap category, three new entries (vechainSwapRouter, wvet, vtho)
• new services/stargate-levels/ — STARGATE_LEVELS + findStargateLevelById/ByTier/ByVet + resolveStargateLevel
• new tools: getStargateLevels, resolveVnsName, resolveToken

Curated read tool (Fase 3)

• getCuratedStargateValidators — wraps getValidators, applies the offline% filter and sorts by nftYieldsIfDelegatedNextCycle[tier]

Clause builders (Fase 4)

New services/clause-builder/ shared module (types, units, encoders, on-chain reads, token resolution) + 12 new MCP tools, all with annotations.destructiveHint: true and readOnlyHint: false so downstream agents can route them onto an exec_clauses event:

• buildSendTokenClauses, buildSwapClauses
• buildStargateStakeAndDelegateClauses, buildStargateDelegateClauses, buildStargateUndelegateClauses, buildStargateClaimRewardsClauses
• buildB3trConvertToVot3Clauses, buildB3trConvertToB3trClauses, buildB3trCastAllocationVotesClauses, buildB3trClaimVoterRewardsClauses, buildB3trCastProposalVoteClauses, buildB3trDelegateVot3Clauses

Each tool returns the canonical { ok, network, data: { clauses, summary, gasHint }, error? } shape. The server NEVER signs or broadcasts.

Parity tests

tests/clause-parity/clause-parity.unit.test.ts — 27 unit tests asserting byte-equal parity with the legacy veworld-b3mo-backend/src/services/clauseBuilder/* output (transfer/approve selectors, exact stake amounts, allowance-conditional approve, tier-vs-amount validation, X-tier rejection, etc.).

Test plan

• npx tsup builds clean
• npx jest tests/clause-parity/ — 27/27 green
• Smoke test against a running MCP: tools/list returns the new tools and the network field appears in every input schema
• Smoke test: call buildSendTokenClauses with network: "testnet" and verify the recipient/value/data match a known fixture
• Smoke test: parallel calls with different network overrides do not leak the Thor client (mainnet/testnet caches stay independent)
• Verify downstream veworld-b3mo-backend agent loop works against this branch end-to-end

[aikido-pr-checks]

8 Open source vulnerabilities detected - critical severity
Aikido detected 8 vulnerabilities across 4 packages, it includes 1 critical and 7 high vulnerabilities.

Details

Remediation Aikido suggests bumping the vulnerable packages to a safe version.

_{Reply @AikidoSec ignore: [REASON] to ignore this issue.}
More info