Skip to main content

How Celestials Works

Overview​

Celestials are human-readable identities in the form of names ending with .i (like alice.i) that resolve to cryptocurrency wallet addresses across different blockchain networks. A celestial like alice.i allows users to share a simple, memorable name instead of complex wallet addresses like 0x742d35Cc6634C0532925a3b8D5c9e4b1e0e5e5. This creates a unified cross-chain identity system.

Celestial Lifecycle​

1. Available Phase​

  • Status: AVAILABLE
  • New celestials start as available for auction
  • Anyone can initiate an auction for an available celestial
  • The celestial exists only as a potential identity at this stage

2. Auction Phase​

  • Status: AUCTION
  • Users participate in auctions to acquire celestials
  • Auctions have configurable durations and bid increments
  • The highest bidder when the auction ends wins the celestial
  • Some celestials may be reserved for specific users or giveaways
  • Bidding extends the auction end time to prevent sniping

3. Auction Ended Phase​

  • Status: AUCTION_ENDED
  • Auction has completed but the celestial hasn't been claimed yet
  • The winning bidder has a claim period to finalize ownership
  • If not claimed within the claim period, the celestial may become available again

4. Owned Phase​

  • Status: OWNED
  • The celestial has been claimed and is actively owned
  • Owner can add/remove addresses for different blockchains
  • Owner can set the celestial for sale
  • Owner can renew to extend the expiry period
  • Owner can revoke (permanently disable) the celestial
  • An NFT represents ownership of the celestial

5. Sale Phase​

  • Status: ON_SALE
  • Active celestial owners can list their celestials for sale at a fixed price
  • Other users can purchase at the listed price
  • Ownership transfers immediately upon purchase
  • The celestial returns to OWNED status under the new owner

6. Expiry and Grace Period​

  • Status: OWNED but expired
  • Celestials have expiry periods (typically 365 days)
  • After expiry, there's a grace period (typically 30 days)
  • During grace period, only the original owner can renew
  • Address resolution may be disabled during this phase
  • If not renewed, the celestial becomes AVAILABLE again

7. Revocation​

  • Status: Permanently disabled
  • Owners can permanently revoke their celestials
  • Revoked celestials cannot be renewed, transferred, or reused
  • This is irreversible and makes the celestial permanently unavailable

Address Verification System​

Celestials can be associated with wallet addresses on multiple blockchain networks. Each address mapping has a verification status that determines its trustworthiness and priority in resolution.

Not Verified​

  • Status: NOT_VERIFIED
  • The address is added but ownership has not been proven
  • Anyone can add addresses to a celestial they own
  • These addresses have the lowest trust level
  • May be filtered out in some resolution queries
  • Useful for initial setup before verification is completed

Verified​

  • Status: VERIFIED
  • Address ownership has been cryptographically proven
  • The user has provided a valid signature proving they control the private key
  • Verification methods vary by blockchain:
    • Ethereum/EVM chains: ECDSA signature verification
    • Cosmos chains: Secp256k1 signature with public key
    • Bitcoin: Bitcoin-specific signature schemes
    • Solana: Ed25519 signature verification
    • Other chains: Chain-specific signature schemes or off-chain verification
  • Verified addresses have higher trust and priority in resolution

Primary Address​

  • Status: PRIMARY
  • Only one celestial can be the primary owner of any address+chain combination
  • When a celestial verifies an address, it becomes PRIMARY for that celestial
  • If another celestial already had PRIMARY status for the same address+chain, it gets downgraded to VERIFIED
  • Primary addresses are returned by default in reverse lookup queries
  • This ensures each address resolves to only one "primary" celestial identity

Cross-Chain Resolution​

Resolution Priority​

When resolving a celestial to an address on a specific chain:

  1. Primary address is returned if it exists for that celestial
  2. Most recent verified address if no primary exists
  3. Most recent unverified address as fallback
  4. Null if no address exists for the requested chain

When performing reverse lookup (address to celestial):

  1. Primary celestial is returned for the address+chain combination
  2. All verified celestials may be returned in some queries
  3. Unverified celestials are typically excluded from reverse lookups

Address Changes​

  • Each address change (add, verify, remove) creates a change record
  • Changes are ordered and can be queried for synchronization
  • External systems can track address updates through change feeds
  • Image regeneration may be triggered on address changes

Supported Chains​

  • The system supports multiple blockchain networks
  • Each chain has a unique identifier (e.g., 0xf043a for Forma)
  • New chains can be added through configuration
  • Chain-specific verification methods handle different signature schemes

Technical Architecture​

NFT Integration​

  • Each owned celestial is represented by an NFT
  • NFT metadata includes celestial name and associated image
  • Images are generated automatically and stored on IPFS
  • NFT ownership follows celestial ownership

Verification Process​

There are two ways to verify address ownership:

Off-chain Verification (API-based)​

  1. User adds an address to their celestial (status: NOT_VERIFIED)
  2. User signs verification message: "I confirm that I control address '{address}' on chain '{chain_id}' and I want to link this address to Celestial '{celestial_id}'."
  3. User calls the /api/verification/verify_address endpoint with:
    • Celestial ID (e.g., alice.i)
    • Address to verify
    • Chain ID (e.g., bitcoin, solana, celestia-1, interwoven-1)
    • Signature of the verification message
    • Public key (for some chains like Cosmos)
  4. System validates the signature using chain-specific verification
  5. If valid, system generates an off-chain signature for contract interaction
  6. User uses this signature to call the registry contract's verification method
  7. Address status updates to VERIFIED and becomes PRIMARY for this celestial

On-chain Verification (Direct contract call)​

  1. User adds an address to their celestial (status: NOT_VERIFIED)
  2. User directly calls the registry contract's verifyAddressWithSignature method with:
    • Celestial ID, chain ID, address, expiry, and signature
  3. Contract validates the signature using the appropriate verifier contract
  4. Address status updates to VERIFIED and becomes PRIMARY for this celestial

Post-verification Effects​

  • Any other celestial that previously had PRIMARY status for the same address chain combination gets downgraded to VERIFIED
  • The address now resolves primarily to the newly verified celestial