Skip to content

[DRAFT] feat: standardize network/asset identifiers via CAIP-2 and CAIP-19#121

Open
MASDXI wants to merge 8 commits into
camaraproject:mainfrom
MASDXI:main
Open

[DRAFT] feat: standardize network/asset identifiers via CAIP-2 and CAIP-19#121
MASDXI wants to merge 8 commits into
camaraproject:mainfrom
MASDXI:main

Conversation

@MASDXI
Copy link
Copy Markdown
Contributor

@MASDXI MASDXI commented May 15, 2026

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

What this PR does:

  • Transitions the blockchainNetworkId from a proprietary :<sub_id> format to the CAIP-2 standard. This allows for a more granular and extensible identification of namespaces (e.g., eip155, cosmos, polkadot, avax).
  • Renames the currency property to assets in both BindBlockchainPublicAddressRequest and BlockchainPublicAddressResponse schemas.
  • Updates the property to strictly enforce the CAIP-19 Asset ID standard via regex (^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}\/[-a-z0-9]{3,8}:[-a-zA-Z0-9]{1,64}$).
  • Updates error codes from BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_CURRENCY to BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_ASSETS (and ASSETS_REQUIRED).
  • Updates the BDD .feature tests to align with the new assets property and error codes.
  • Expands the OpenAPI description examples to clearly illustrate cross-chain routing (e.g., distinguishing between Avalanche C-Chain, X-Chain, and Moonbeam precompiles).

Why we need it:

  • Adopting CAIP-2 and CAIP-19 ensures the API It allows for the use of aliases (e.g., evmos identified as both cosmos:evmos_9000-1 and eip155:9000) to ensure compatibility across different wallet and provider ecosystems.
  • Blockchains support vastly more than just currency (e.g., Fugible Token, Non-Fungible Tokens (NFTs), Soulbound Tokens (SBTs)) "asset" is the correct terminology. Pluralizing to assets also correctly matches the array data type.
  • Relying on simple ticker symbols (like ETH or AVAX) is ambiguous in modern Web3 environments. For example, AVAX exists on three different native chains (X, P, C) with different address formats. Standardizing on CAIP-19 and SLIP-44 solves the routing problem and ensures API consumers can definitively identify the network and asset type.

Which issue(s) this PR fixes:

issue: #72

Special notes for reviewers:

Warning

Breaking Change Alert for vwip

  • This PR introduces the transition blockchainNetworkId from a proprietary format to the CAIP-2 standard.
  • This PR introduces a schema-breaking change by dropping the currency key in favor of assets. Implementers currently using the vwip (Work In Progress) spec will need to update their request payloads and error handling logic to accommodate BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_ASSETS.
  • Please review the updated BDD test scenarios (@bind_blockchain_public_address_400.06_invalid_assets and @bind_blockchain_public_address_400.07_missing_assets) to ensure alignment with Telco Operator business rules.

Changelog input

feat: migrate to CAIP-2/19 standards, renaming 'currency' to 'assets' and updating associated validation, error codes, and BDD suites.

Additional documentation

  • Integrated external technical references for CAIP-2 (Chain ID), CAIP-19 (Asset ID), and the SLIP-44 Registry directly into property descriptions.
  • Added comprehensive examples for multi-chain routing, specifically addressing Avalanche (X/P/C-Chains), Moonbeam parachains, and L3 networks to resolve address/asset ambiguity.

@MASDXI MASDXI changed the title feat: transition from currency to CAIP-19 assets standard. [DRAFT] feat: transition from currency to CAIP-19 assets standard. May 15, 2026
@MASDXI MASDXI changed the title [DRAFT] feat: transition from currency to CAIP-19 assets standard. [DRAFT] feat: standardize network/asset identifiers via CAIP-2 and CAIP-19 May 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant