Add ENS resolution design doc for XMTP extension by neekolas · Pull Request #26 · xmtplabs/openclaw

neekolas · 2026-02-16T20:30:38Z

Summary

Problem: XMTP extension lacked ENS name resolution, requiring users to work with raw Ethereum addresses
Why it matters: ENS names provide human-readable identifiers, improving usability and context for the agent
What changed: Added ENS resolution throughout the XMTP extension using web3.bio API with caching
What did NOT change: No changes to the core XMTP protocol integration or message format

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #ENS-123

User-visible / Behavior Changes

ENS names in messages are resolved and included as context for the agent
Ethereum addresses in messages are reverse-resolved to ENS names when available
Configuration fields (ownerAddress, allowFrom) now accept ENS names
Conversation participants are resolved to ENS names and provided as context
Agent is instructed to refer to addresses by ENS name when available
Added optional web3BioApiKey config field for higher rate limits

Security Impact (required)

New permissions/capabilities? (No)
Secrets/tokens handling changed? (Yes)
New/changed network calls? (Yes)
Command/tool execution surface changed? (No)
Data access scope changed? (No)
If any Yes, explain risk + mitigation:
- Added optional web3BioApiKey config field - stored like other API keys
- New network calls to web3.bio API - public data only, graceful failure handling

Repro + Verification

Environment

OS: macOS 14.3
Runtime/container: Node.js 18.x
Model/provider: Claude 3 Opus
Integration/channel: XMTP
Relevant config: { "web3BioApiKey": "optional-key" }

Steps

Configure XMTP extension with ownerAddress: "vitalik.eth"
Start the extension
Send a message containing ENS names or Ethereum addresses
Observe agent response using ENS names

Expected

Agent receives ENS context for addresses/names in messages
Agent refers to users by ENS names instead of addresses
DM policy correctly resolves ENS names in allowFrom list

Actual

Same as expected

Evidence

Passing tests for all components
Manual verification with ENS names in messages

Human Verification (required)

What you personally verified (not just CI), and how:

Verified scenarios: ENS resolution in messages, config fields, and DM policy
Edge cases checked: Failed resolution, caching behavior, rate limiting
What you did not verify: Long-term performance impact of caching

Compatibility / Migration

Backward compatible? (Yes)
Config/env changes? (Yes)
Migration needed? (No)
If yes, exact upgrade steps: N/A

Failure Recovery (if this breaks)

How to disable/revert this change quickly: Remove web3BioApiKey from config
Files/config to restore: No critical files to restore
Known bad symptoms reviewers should watch for: Excessive API calls to web3.bio

Risks and Mitigations

Risk: Rate limiting from web3.bio API
- Mitigation: Implemented caching with 5-minute TTL and optional API key
Risk: ENS resolution adds latency to message processing
- Mitigation: Parallel resolution and caching minimize impact

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…actEnsNames, extractEthAddresses) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…and retry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add web3BioApiKey config field to config-types.ts and config-schema.ts - Update onboarding to accept ENS names for ownerAddress field - Import isEnsName helper to validate ENS format - Update prompt message, placeholder, and validator to handle both addresses and ENS names Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…names Wire ENS resolver into XMTP gateway lifecycle: create resolver instance after agent creation, resolve ownerAddress if it's an ENS name before opening the owner DM, and clean up the resolver on agent stop. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… access check Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ipeline Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…t on inbound Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

neekolas · 2026-02-16T20:30:49Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

This stack of pull requests is managed by Graphite. Learn more about stacking.

macroscopeapp · 2026-02-16T20:31:52Z

Add ENS resolution across XMTP to accept ENS inputs, resolve names with a 5‑minute cached web3.bio resolver, and enrich inbound/outbound messaging with ENS context

Introduce a per‑account ENS resolver and wire it into onboarding, DM policy, gateway lifecycle, inbound handlers, outbound send paths, and agent hints; pass senderName, groupMembers, and ensContext through the pipeline and prepend ENS context to message bodies; add web3BioApiKey config; include a design doc and tests.

📍Where to Start

Start with resolver creation and usage in gateway-lifecycle.startAccount in gateway-lifecycle.ts, then follow the ENS fields through channel handlers to runInboundPipeline in inbound-pipeline.ts.

Macroscope summarized 1eafe3d.

github-actions · 2026-02-16T20:32:20Z

⚠️ Formal models conformance drift detected

The formal models extracted constants (generated/*) do not match this openclaw PR.

This check is informational (not blocking merges yet).
See the formal-models-conformance-drift artifact for the diff.

If this change is intentional, follow up by updating the formal models repo or regenerating the extracted artifacts there.

neekolas and others added 14 commits February 15, 2026 23:49

Add ENS resolution design doc for XMTP extension

6e60073

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add ENS resolution implementation plan

e326355

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(xmtp): add ENS extraction helpers (isEnsName, isEthAddress, extr…

b5cfd8b

…actEnsNames, extractEthAddresses) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(xmtp): add ENS resolver with web3.bio API integration, caching, …

19f2f9a

…and retry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(xmtp): add per-account ENS resolver instance management

f10ebcb

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(xmtp): resolve ENS names in ownerAddress and allowFrom during DM…

a030fc7

… access check Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(xmtp): add ENS context and group member formatting helpers

5c7e3a6

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(xmtp): wire ENS context, SenderName, GroupMembers into inbound p…

668642f

…ipeline Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(xmtp): resolve ENS for sender, group members, and message conten…

30c51d5

…t on inbound Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(xmtp): add ENS-aware agent prompt hints and target resolution

f48572b

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(xmtp): resolve ENS names for outbound message targets

c01a0dc

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add zed config

1eafe3d

neekolas mentioned this pull request Feb 16, 2026

feat(xmtp): add XMTP extension with type fixes for current API #23

Draft

16 tasks

This was referenced Feb 16, 2026

Add reactions support and account autocreation #24

Draft

Add full media support and owner address #25

Draft

Get up to date with OpenClaw main #22

Draft

Update fly.io config #28

Draft

Refactor XMTP Extension And Fix Bugs #27

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add ENS resolution design doc for XMTP extension#26

Add ENS resolution design doc for XMTP extension#26
neekolas wants to merge 14 commits into
02-15-improve_media_upload_supportfrom
02-15-add_ens_resolution

neekolas commented Feb 16, 2026 •

edited

Loading

Uh oh!

neekolas commented Feb 16, 2026 •

edited

Loading

Uh oh!

macroscopeapp Bot commented Feb 16, 2026

Uh oh!

github-actions Bot commented Feb 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

neekolas commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Uh oh!

neekolas commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

macroscopeapp Bot commented Feb 16, 2026

Add ENS resolution across XMTP to accept ENS inputs, resolve names with a 5‑minute cached web3.bio resolver, and enrich inbound/outbound messaging with ENS context

📍Where to Start

Uh oh!

github-actions Bot commented Feb 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

neekolas commented Feb 16, 2026 •

edited

Loading

neekolas commented Feb 16, 2026 •

edited

Loading