@defuse-protocol/crosschain-assetid 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# 1cs_v1 — Unified Cross-Chain Asset Identifier
+
+## Installation
+
+```bash
+npm install @defuse-protocol/crosschain-assetid
+```
+
+## Usage
+
+```typescript
+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
+
+| Part          | Required? | Description                                                                                                                                      |
+|---------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| `1cs_v1`      | ✅         | Format prefix and version. 1cs stands for [1ClickSwap](https://docs.near-intents.org/near-intents/integration/distribution-channels/1click-api). |
+| `<chain>`     | ✅         | Lowercase slug (e.g. `eth`, `eth-sepolia`, `solana`, `near`, `polygon`), can encode testnet in slug.                                             |
+| `<namespace>` | ✅         | Asset standard/kind: `erc20`, `erc721`, `spl`, `near-nft`, `aptos-coin`, `fiat`, etc.                                                            |
+| `<reference>` | ✅         | Contract/mint/account/denom/issuer — **URI-encoded** to safely hold `:`, `/`, spaces, unicode, etc.                                              |
+| `<selector>`  | optional  | Sub-asset selector: token ID, module struct, Stellar code, etc. — also **URI-encoded**.                                                          |
+
+---
+
+## 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
+```
+
+---
+
+## 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:
+
+```ts
+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"
+}
+```

package/dist/index.cjs

@@ -0,0 +1,102 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  fromUniswapToken: () => fromUniswapToken,
+  parse1cs: () => parse1cs,
+  stringify1cs: () => stringify1cs
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/parse.ts
+function parse1cs(s) {
+  const parts = s.split(":");
+  if (parts.length < 4 || parts.length > 5 || parts[0] !== "1cs_v1") {
+    throw new Error("Invalid 1cs_v1 string");
+  }
+  const [_, chain, namespace, refEnc, selEnc] = parts;
+  const obj = {
+    version: "v1",
+    // biome-ignore lint/style/noNonNullAssertion: existence checked above
+    chain,
+    // biome-ignore lint/style/noNonNullAssertion: existence checked above
+    namespace,
+    // biome-ignore lint/style/noNonNullAssertion: existence checked above
+    reference: decodeURIComponent(refEnc)
+  };
+  if (selEnc !== void 0) obj.selector = decodeURIComponent(selEnc);
+  return obj;
+}
+
+// src/stringify.ts
+function stringify1cs(o) {
+  const ref = encodeURIComponent(o.reference);
+  const sel = o.selector != null ? `:${encodeURIComponent(o.selector)}` : "";
+  return `1cs_v1:${o.chain}:${o.namespace}:${ref}${sel}`;
+}
+
+// src/caip2-slug-registry.json
+var caip2_slug_registry_default = {
+  "eip155:1": "eth",
+  "eip155:10": "optimism",
+  "eip155:56": "bsc",
+  "eip155:100": "gnosis",
+  "eip155:137": "polygon",
+  "eip155:8453": "base",
+  "eip155:42161": "arbitrum",
+  "eip155:43114": "avalanche",
+  "eip155:80085": "berachain",
+  "bip122:000000000019d6689c085ae165831e93": "bitcoin",
+  "bip122:00040fe8ec8471911baa1db1266ea15d": "zcash",
+  "bip122:1a91e3dace36e2be3bf030a65679fe82": "doge",
+  "near:mainnet": "near",
+  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "sol",
+  "tron:27Lqcw": "tron",
+  "xrpl:0": "xrpl",
+  "tvm:-239": "ton",
+  "sui:mainnet": "sui",
+  "aptos:mainnet": "aptos",
+  "stellar:pubnet": "stellar",
+  "cip34:1-764824073": "cardano"
+};
+
+// src/uniswap.ts
+var evmSlugRegistry = caip2_slug_registry_default;
+function fromUniswapToken(token, caip2slugMap) {
+  const caip2 = `eip155:${token.chainId}`;
+  const chain = caip2slugMap?.[caip2] ?? evmSlugRegistry[caip2];
+  if (chain == null) {
+    throw new Error(`Unsupported chainId = ${token.chainId}`);
+  }
+  const o = {
+    version: "v1",
+    chain,
+    namespace: "erc20",
+    reference: token.address
+  };
+  return stringify1cs(o);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fromUniswapToken,
+  parse1cs,
+  stringify1cs
+});

package/dist/index.d.cts

@@ -0,0 +1,19 @@
+interface OneCsAsset {
+    version: "v1";
+    chain: string;
+    namespace: string;
+    reference: string;
+    selector?: string;
+}
+
+declare function parse1cs(s: string): OneCsAsset;
+
+declare function stringify1cs(o: OneCsAsset): string;
+
+interface UniToken {
+    chainId: number;
+    address: string;
+}
+declare function fromUniswapToken<T extends UniToken>(token: T, caip2slugMap?: Record<string, string>): string;
+
+export { type OneCsAsset, type UniToken, fromUniswapToken, parse1cs, stringify1cs };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+interface OneCsAsset {
+    version: "v1";
+    chain: string;
+    namespace: string;
+    reference: string;
+    selector?: string;
+}
+
+declare function parse1cs(s: string): OneCsAsset;
+
+declare function stringify1cs(o: OneCsAsset): string;
+
+interface UniToken {
+    chainId: number;
+    address: string;
+}
+declare function fromUniswapToken<T extends UniToken>(token: T, caip2slugMap?: Record<string, string>): string;
+
+export { type OneCsAsset, type UniToken, fromUniswapToken, parse1cs, stringify1cs };

package/dist/index.js

@@ -0,0 +1,73 @@
+// src/parse.ts
+function parse1cs(s) {
+  const parts = s.split(":");
+  if (parts.length < 4 || parts.length > 5 || parts[0] !== "1cs_v1") {
+    throw new Error("Invalid 1cs_v1 string");
+  }
+  const [_, chain, namespace, refEnc, selEnc] = parts;
+  const obj = {
+    version: "v1",
+    // biome-ignore lint/style/noNonNullAssertion: existence checked above
+    chain,
+    // biome-ignore lint/style/noNonNullAssertion: existence checked above
+    namespace,
+    // biome-ignore lint/style/noNonNullAssertion: existence checked above
+    reference: decodeURIComponent(refEnc)
+  };
+  if (selEnc !== void 0) obj.selector = decodeURIComponent(selEnc);
+  return obj;
+}
+
+// src/stringify.ts
+function stringify1cs(o) {
+  const ref = encodeURIComponent(o.reference);
+  const sel = o.selector != null ? `:${encodeURIComponent(o.selector)}` : "";
+  return `1cs_v1:${o.chain}:${o.namespace}:${ref}${sel}`;
+}
+
+// src/caip2-slug-registry.json
+var caip2_slug_registry_default = {
+  "eip155:1": "eth",
+  "eip155:10": "optimism",
+  "eip155:56": "bsc",
+  "eip155:100": "gnosis",
+  "eip155:137": "polygon",
+  "eip155:8453": "base",
+  "eip155:42161": "arbitrum",
+  "eip155:43114": "avalanche",
+  "eip155:80085": "berachain",
+  "bip122:000000000019d6689c085ae165831e93": "bitcoin",
+  "bip122:00040fe8ec8471911baa1db1266ea15d": "zcash",
+  "bip122:1a91e3dace36e2be3bf030a65679fe82": "doge",
+  "near:mainnet": "near",
+  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "sol",
+  "tron:27Lqcw": "tron",
+  "xrpl:0": "xrpl",
+  "tvm:-239": "ton",
+  "sui:mainnet": "sui",
+  "aptos:mainnet": "aptos",
+  "stellar:pubnet": "stellar",
+  "cip34:1-764824073": "cardano"
+};
+
+// src/uniswap.ts
+var evmSlugRegistry = caip2_slug_registry_default;
+function fromUniswapToken(token, caip2slugMap) {
+  const caip2 = `eip155:${token.chainId}`;
+  const chain = caip2slugMap?.[caip2] ?? evmSlugRegistry[caip2];
+  if (chain == null) {
+    throw new Error(`Unsupported chainId = ${token.chainId}`);
+  }
+  const o = {
+    version: "v1",
+    chain,
+    namespace: "erc20",
+    reference: token.address
+  };
+  return stringify1cs(o);
+}
+export {
+  fromUniswapToken,
+  parse1cs,
+  stringify1cs
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@defuse-protocol/crosschain-assetid",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./schemas/1cs_v1-object.schema.json": "./schemas/1cs_v1-object.schema.json",
+    "./schemas/1cs_v1-string.schema.json": "./schemas/1cs_v1-string.schema.json"
+  },
+  "files": [
+    "dist",
+    "schemas"
+  ],
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/schemas/1cs_v1-object.schema.json

@@ -0,0 +1,52 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://example.com/1cs_v1-object.schema.json",
+	"title": "1cs_v1 asset (object form, encodeURIComponent on stringify)",
+	"type": "object",
+	"additionalProperties": false,
+	"properties": {
+		"version": {
+			"const": "v1"
+		},
+		"chain": {
+			"type": "string",
+			"pattern": "^[a-z0-9][a-z0-9-]*$"
+		},
+		"namespace": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*$"
+		},
+		"reference": {
+			"type": "string",
+			"minLength": 1,
+			"description": "RAW (decoded) value; will be encodeURIComponent()'d when stringified."
+		},
+		"selector": {
+			"type": "string",
+			"minLength": 1,
+			"description": "RAW (decoded) sub-id; will be encodeURIComponent()'d when stringified."
+		}
+	},
+	"required": ["version", "chain", "namespace", "reference"],
+	"examples": [
+		{
+			"version": "v1",
+			"chain": "eth",
+			"namespace": "erc20",
+			"reference": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+		},
+		{
+			"version": "v1",
+			"chain": "near",
+			"namespace": "near-nft",
+			"reference": "apes.coolnft.near",
+			"selector": "series.1:blue/42"
+		},
+		{
+			"version": "v1",
+			"chain": "fiat",
+			"namespace": "iso4217",
+			"reference": "EUR"
+		}
+	]
+}

package/schemas/1cs_v1-string.schema.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://example.com/1cs_v1-string.schema.json",
+	"title": "1cs_v1 asset ID (string, URI-component encoding)",
+	"type": "string",
+	"$defs": {
+		"uriComponent": {
+			"type": "string",
+			"pattern": "^(?:[A-Za-z0-9\\-_.!~*'()]|%[0-9A-Fa-f]{2})+$"
+		},
+		"chain": {
+			"type": "string",
+			"pattern": "^[a-z0-9][a-z0-9-]*$"
+		},
+		"namespace": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*$"
+		}
+	},
+	"pattern": "^1cs_v1:[a-z0-9][a-z0-9-]*:[a-z][a-z0-9-]*:(?:[A-Za-z0-9\\-_.!~*'()]|%[0-9A-Fa-f]{2})+(?::(?:[A-Za-z0-9\\-_.!~*'()]|%[0-9A-Fa-f]{2})+)?$",
+	"examples": [
+		"1cs_v1:eth:erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+		"1cs_v1:eth-sepolia:erc721:0xAbcDEF1234567890abcdef1234567890ABCDef12:42",
+		"1cs_v1:near:near-nft:apes.coolnft.near:series.1%3Ablue%2F42",
+		"1cs_v1:aptos:aptos-coin:0x1%3A%3Aaptos_coin%3A%3AAptosCoin",
+		"1cs_v1:fiat:iso4217:EUR"
+	]
+}