1cs_v1 — Unified Cross-Chain Asset Identifier

Installation

npm install @defuse-protocol/crosschain-assetid

Usage

import {parse1cs, stringify1cs} from '@defuse-protocol/crosschain-assetid';

const assetid = stringify1cs({
  version: "v1",
  chain: "eth",
  namespace: "erc20",
  reference: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
})

const obj = parse1cs("1cs_v1:eth:erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48")

Purpose

1cs_v1 is a URL-safe, compact, human-readable identifier format for representing any asset (crypto token, NFT, native coin, wrapped/bridged asset, or even fiat) across chains in a consistent way.

It is designed to:

• Let apps refer to assets unambiguously without chain-specific parsing logic.
• Work cross-chain and cross-standard — one format for EVM, Solana, Cosmos, NEAR, Stellar, Aptos, Sui, fiat, etc.
• Be safe in URLs, filenames, and APIs without extra escaping.
• Enable simple parsing into an object with predictable fields.
• Serve as a unified key for balances, swaps, bridges, quotes, and off-ramps.

Format

1cs_v1:<chain>:<namespace>:<reference>[:<selector>]

Components

Examples

Fungible tokens

1cs_v1:eth:erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48    # USDC on Ethereum
1cs_v1:base:erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913   # USDC on Base
1cs_v1:fiat:iso4217:USD                                        # US Dollar (fiat)

NFTs

1cs_v1:eth:erc721:0x1234567890abcdef1234567890abcdef12345678:42
1cs_v1:near:nep171:apes.coolnft.near:series%3A1%2Fblue%3A42

Native coins

1cs_v1:eth:native:coin
1cs_v1:zcash:native:coin

Non-EVM standards

1cs_v1:solana:spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
1cs_v1:aptos:aptos-coin:0x1%3A%3Aaptos_coin%3A%3AAptosCoin
1cs_v1:aptos:aptos-fa:0x0b0b819dcf8d9517ed14195a95adfae6a49bfdb49de33a532ca0aa7ee588e8e0

Aptos has two fungible-token standards, so reference takes a different shape for each:

• aptos-coin — legacy Coin<T> standard. reference is the fully-qualified Move struct type (address::module::Struct).
• aptos-fa — Fungible Asset standard (AIP-21). reference is the plain object address holding the 0x1::fungible_asset::Metadata resource.

Rationale & Design Choices

1. URL safety

We encode reference and selector with encodeURIComponent so they are safe in URLs.

2. Human-readable but unambiguous

• Prefix (1cs_v1) makes it clear what format is in use. Easy greppable across codebase.
• Chain slug + namespace covers most identification needs without extra lookups.
• Works for both blockchain and fiat.

3. Multi-asset support

selector cleanly supports ERC-1155 IDs, Stellar asset codes, Cosmos token sub-denoms, Aptos/Sui struct names, etc.

4. Bridged / wrapped assets

The ID identifies the on-chain representation. If you need to express the origin, bridge, issuer, or other metadata — pass it as query params or in your object model, not in the core ID.

Object Form

Parsing a 1cs_v1 string gives you:

interface OneCsAsset {
    version: "v1";
    chain: string;      // e.g. "eth", "near", "fiat"
    namespace: string;  // e.g. "erc20", "spl", "native"
    reference: string;  // decoded from URI
    selector?: string;  // decoded from URI if present
}

Example:

1cs_v1:near:nep171:apes.coolnft.near:series%3A1%2Fblue%3A42
↓
{
  version: "v1",
  chain: "near",
  namespace: "nep171",
  reference: "apes.coolnft.near",
  selector: "series:1/blue:42"
}