namespaces icon indicating copy to clipboard operation
namespaces copied to clipboard

Add Stellar namespace CAIP-10 and CAIP-19 specifications

Open pelle opened this issue 1 month ago • 1 comments

Summary

This PR adds comprehensive Chain Agnostic Improvement Proposal (CAIP) specifications for the Stellar namespace:

  • CAIP-10: Address specification covering all Stellar address formats
  • CAIP-19: Asset specification covering all Stellar asset types

CAIP-10: Stellar Addresses

Address Formats Supported

  1. Classic G-addresses (56 characters)

    • Standard Ed25519 public key addresses
    • Optional memo support with hyphen separator for destination tags
    • Supports MEMO_TEXT, MEMO_ID, and MEMO_HASH types
  2. Muxed M-addresses (69 characters)

    • Encodes both G-address and 64-bit memo ID in single string
    • Introduced in Protocol 13 (CAP-27)
    • Provides safer alternative to separate memos

Key Features

  • Comprehensive documentation of memo types and their use cases
  • Emphasis on critical importance of memos for exchange transactions
  • Examples for pubnet, testnet, and devnet
  • Proper references to SEP-23 (Strkeys), CAP-27 (Muxed Accounts), and SEP-0002 (Federation)

CAIP-19: Stellar Assets

Asset Types Covered

  1. Native Asset (slip44:148)

    • XLM/lumens using SLIP-44 coin type registry
    • Follows CAIP-20 standard for native assets
  2. Issued Assets (asset)

    • Unified namespace for both AlphaNum4 (≤4 chars) and AlphaNum12 (5-12 chars)
    • Format: {asset_code}-{issuer_address} using hyphen delimiter
    • Asset codes are 1-12 printable ASCII characters
  3. Liquidity Pool Shares (cap38)

    • Introduced in Protocol 18
    • Identified by deterministic SHA-256 pool ID hash
    • Non-transferable, represent fractional pool ownership
  4. Soroban Contract Tokens (sep41)

    • Introduced in Protocol 20
    • Follows SEP-41 token interface standard
    • Includes Stellar Asset Contracts (SAC) and custom tokens
    • Contract addresses are 56-character strkeys starting with 'C'

Design Decisions

  • SLIP-44 for native asset: Uses standard coin type 148 for XLM, following CAIP-20
  • Unified asset namespace: Consolidates AlphaNum4 and AlphaNum12 into single asset namespace for simplicity
  • Hyphen delimiter: Uses - instead of : to separate asset code from issuer address
  • Protocol-specific namespaces: Uses cap38 and sep41 to directly reference the defining protocol specifications

Comprehensive Coverage

  • Detailed syntax and regex patterns for each asset type
  • Clear semantics explaining when and how each type is used
  • Real-world examples for all asset types across different networks
  • Backwards compatibility notes for each protocol version
  • Proper references to CAP-38, CAP-46-6, SEP-41, and SLIP-44

pelle avatar Nov 06 '25 06:11 pelle

Design Decisions SLIP-44 for native asset: Uses standard coin type 148 for XLM, following CAIP-20 Unified asset namespace: Consolidates AlphaNum4 and AlphaNum12 into single asset namespace for simplicity Hyphen delimiter: Uses - instead of : to separate asset code from issuer address Protocol-specific namespaces: Uses cap38 and sep41 to directly reference the defining protocol specifications

These all seem entirely defensible, but just in case, could you maybe tag some Stellar devs for a review just in case these decisions are controversial among devs who would implement this some day, whether on a CEX or a wallet or another kind of dapp?

bumblefudge avatar Nov 06 '25 18:11 bumblefudge