Skip to main content

Explorer Integration

A comprehensive guide for integrating Celestials multi-chain naming service into blockchain explorer applications.

Overview​

Celestials enables users to register human-readable names (like alice.i) that resolve to wallet addresses across multiple blockchain networks. For blockchain explorers, this provides enhanced user experience by displaying meaningful names instead of raw addresses in transaction histories and account pages.

API Endpoints:

Integration Patterns​

1. Index Address Changes (Primary Pattern)​

Use Case: Keep your explorer's celestial-to-address mapping synchronized with real-time updates.

curl https://api.celestials.id/api/resolver/changes \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "chain_id": "0xf043a",
    "from_change_id": 0,
    "limit": 50,
    "with_images": true
  }'

Response:

{
  "head": 17068,
  "changes": [
    {
      "celestial_id": "blather.i",
      "change_id": 7,
      "address": "0x673004082f0fDcF9563a3020aaE87891FbbdDC47",
      "status": "PRIMARY",
      "image_url": "https://ipfs.io/ipfs/QmaiFPgSFGbZ3KgK6QE1AXcY6H8kytZ2eAopwhDN4vvQ8k"
    },
    {
      "celestial_id": "mammoths.i",
      "change_id": 16,
      "address": null,
      "status": "NOT_VERIFIED",
      "image_url": "https://ipfs.io/ipfs/QmdeqAYKMDAcrzw3bdgPrBcazhE5Uo9bwmQ2Mwip1i1UMD"
    }
  ]
}

Implementation Pattern:

  1. Start with from_change_id: 0 for initial sync
  2. Store the returned head value as your last processed change ID
  3. Periodically poll using the stored head as from_change_id
  4. Process changes sequentially to maintain consistency

2. Display Celestial Names in Transaction History​

Use Case: Show celestial names for addresses in transaction lists and account pages.

curl https://api.celestials.id/api/resolver/primary_reverse_lookup \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "addresses": [
      "0x742d35Cc6634C0532925a3b8D5c9e4b1e0e5e5",
      "0x123d35Cc6634C0532925a3b8D5c9e4b1e0e5e5"
    ],
    "chain_id": "0xf043a"
  }'

Response:

{
  "primary_celestials": {
    "0x742d35Cc6634C0532925a3b8D5c9e4b1e0e5e5": "alice.i",
    "0x123d35Cc6634C0532925a3b8D5c9e4b1e0e5e5": "bob.i"
  }
}

3. Resolve Names for Search Functionality​

Use Case: Allow users to search for celestial names and navigate to corresponding addresses.

curl https://api.celestials.id/api/resolver/primary_lookup \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "celestial_ids": ["alice.i"],
    "chain_id": "0xf043a"
  }'

Response:

{
  "primary_addresses": {
    "alice.i": "0x742d35Cc6634C0532925a3b8D5c9e4b1e0e5e5"
  }
}

Supported Blockchain Networks​

Retrieve the list of currently supported chains:

curl https://api.celestials.id/api/resolver/chains

Address Verification System​

Understanding verification levels helps explorers provide accurate information about celestial-to-address relationships.

Verification Levels​

NOT_VERIFIED

  • Address added without cryptographic proof of ownership
  • Should be displayed with caution indicators
  • May represent invalid or malicious mappings

VERIFIED

  • Ownership confirmed through cryptographic signature validation
  • Trustworthy address association
  • Safe to display as confirmed mapping

PRIMARY

  • The authoritative celestial for a specific address on a given chain
  • Only one celestial can hold PRIMARY status per address per chain
  • Recommended for prominent display in explorer interfaces
  • Most reliable mapping for user identification

Indexing Recommendations​

Change Processing Strategy​

Incremental Sync:

  • Poll the changes endpoint every 30-60 seconds
  • Process changes in order by change_id
  • Handle address removals (when address is null)
  • Update your local cache/database with new mappings

Batch Processing:

  • Use large limit values (1000+) for initial sync
  • Implement pagination for large change sets
  • Monitor the head value to detect when you're caught up

Caching Strategy​

For optimal performance, explorers should maintain local caches of celestial-to-address mappings, updating them through the changes feed rather than making lookup requests for every page view.

Support​

For technical questions, integration assistance, or testnet token requests, contact: support@celestials.id

API overview: https://celestials.id/docs/api-overview Interactive documentation: https://api.celestials.id/scalar