DEV Community

Rastislav ₡ORE
Rastislav ₡ORE

Posted on • Edited on

Building a Well-Known Token Registry

#wellknown #token #blockchain #registry

The Problem: Token Discovery Chaos

In the blockchain ecosystem, one of the most persistent challenges is token discovery and validation. Every day, thousands of new tokens are created across different blockchains, but there's no standardized way for applications to discover and validate them.

Current Pain Points

  • Fragmented Data Sources: Token metadata is scattered across multiple APIs, websites, and databases
  • Inconsistent Formats: Each platform uses different data structures and validation methods
  • No Standard Discovery: Applications must maintain their own token lists or rely on centralized services
  • Validation Complexity: Each blockchain has different address formats and validation rules
  • Maintenance Overhead: Developers spend significant time maintaining token lists and validation logic

The Solution: Well-Known Token Registry

The solution can be a Well-Known Token Registry that leverages the established .well-known URI specification to provide a standardized, discoverable way to access token information across the web.

What is .well-known?

The .well-known URI specification (RFC 8615) defines a standard way to provide metadata about a service at a predictable location. It's used by major services like:

  • OAuth providers (/.well-known/oauth-authorization-server)
  • OpenID Connect (/.well-known/openid_configuration)
  • Security policies (/.well-known/security.txt)
  • WebFinger (/.well-known/webfinger)

By following this standard, we ensure that our token registry is:

  • ✅ Discoverable at predictable URLs
  • ✅ Interoperable with existing web infrastructure
  • ✅ Standardized following established conventions
  • ✅ Cacheable by CDNs and browsers

Architecture Overview

The solution is built on Serverless Functions with the following architecture:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Client App    │───▶│  Serverless      │───▶│   Storage       │
│   (Wallet/DEX)  │    │  Functions       │    │   (Token Data)  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │  Information     │
                       │  (Address Check) │
                       └──────────────────┘
Enter fullscreen mode Exit fullscreen mode

API Endpoints

Status Endpoints

Health Check 

GET https://coreblockchain.net/.well-known/tokens/status/ping
# Response: "pong"
Enter fullscreen mode Exit fullscreen mode

Version Information 

GET https://coreblockchain.net/.well-known/tokens/status/version
# Response: {"version": "0.1.0", "environment": "prod"}
Enter fullscreen mode Exit fullscreen mode

Detailed Health 

GET https://coreblockchain.net/.well-known/tokens/status/health
# Response: {"currentTime": "2024-01-15T10:30:00.000Z", "health": "ok"}
Enter fullscreen mode Exit fullscreen mode

Token Endpoints

List All Tokens 

GET https://coreblockchain.net/.well-known/tokens.json?prefix=cb&limit=50
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "tokens": [
    "cb19c7acc4c292d2943ba23c2eaa5d9c5a6652a8710c"
  ],
  "pagination": {
    "limit": 50,
    "hasNext": true,
    "cursor": "6Ck1la0VxJ0djhidm1MdX2FyD"
  }
}
Enter fullscreen mode Exit fullscreen mode

Get Specific Token 

GET https://coreblockchain.net/.well-known/tokens/cb19c7acc4c292d2943ba23c2eaa5d9c5a6652a8710c.json
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "ticker": "CTN",
  "name": "CoreToken",
  "decimals": 18,
  "symbol": "Ƈ",
  "type": "CBC20",
  "url": "https://coretoken.net",
  "logos": [
    {
      "size": 16,
      "type": "image/svg+xml",
      "url": "https://corecdn.info/mark/16/coretoken.svg"
    },
    …
  ]
}
Enter fullscreen mode Exit fullscreen mode

Benefits:

  • ✅ Scalable: Handles thousands of tokens efficiently
  • ✅ Consistent: Results remain stable across pagination
  • ✅ Network-friendly: Minimal data transfer

3. Prefix Filtering

Support for filtering tokens by address prefix:

# Get all tokens starting with "cb11"
GET /.well-known/tokens.json?prefix=cb11
Enter fullscreen mode Exit fullscreen mode

Route Configuration 

// Status endpoints
app.get("/.well-known/tokens/status/ping", Ping);
app.get("/.well-known/tokens/status/version", Version);
app.get("/.well-known/tokens/status/health", Health);

// Token endpoints
app.get("/.well-known/tokens.json", listAllTokens);
app.get("/.well-known/tokens/:token.json", getToken);
Enter fullscreen mode Exit fullscreen mode

Security Considerations

  1. Input Validation: All inputs should be validated
  2. Rate Limiting: Ensure built-in DDoS protection is in place
  3. CORS: Properly configure for cross-origin requests
  4. Environment Separation: Different validation rules for production and development

Future Improvements

The storage can be connected to multiple sources. Some examples may include:

  • KV storage
  • IPFS database (like OrbitDB)
  • Blockchain data itself

Benefits for the Ecosystem

For Developers

  • Reduced Complexity: No need to maintain token lists
  • Standardized API: Consistent interface across all tokens
  • Built-in Validation: Address validation handled automatically
  • High Performance: Global CDN distribution

For Users

  • Faster Loading: Optimized token discovery
  • Better UX: Consistent token information across applications
  • Reliability: Based on proven web standards

For the Industry

  • Interoperability: Standardized token discovery
  • Decentralization: No single point of failure
  • Transparency: Open source and auditable
  • Scalability: Can handle growing token ecosystem

Conclusion

The Well-Known Token Registry demonstrates how established web standards can solve modern blockchain challenges. By leveraging the .well-known URI specification, we've created a solution that is:

  • Discoverable: Easy to find and integrate
  • Standardized: Follows established conventions
  • Scalable: Built for the growing Blockchain ecosystem
  • Reliable: Powered by a global CDN infrastructure & selected storage

Resources

Top comments (0)