lampamazaza-new-crosschain-assetid 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NEAR Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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,74 @@
+
+//#region 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",
+		chain,
+		namespace,
+		reference: decodeURIComponent(refEnc)
+	};
+	if (selEnc !== void 0) obj.selector = decodeURIComponent(selEnc);
+	return obj;
+}
+
+//#endregion
+//#region 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}`;
+}
+
+//#endregion
+//#region 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:143": "monad",
+	"eip155:196": "xlayer",
+	"eip155:8453": "base",
+	"eip155:36900": "adi",
+	"eip155:42161": "arbitrum",
+	"eip155:43114": "avalanche",
+	"eip155:80085": "berachain",
+	"eip155:9745": "plasma",
+	"eip155:534352": "scroll",
+	"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"
+};
+
+//#endregion
+//#region src/uniswap.ts
+const 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}`);
+	return stringify1cs({
+		version: "v1",
+		chain,
+		namespace: "erc20",
+		reference: token.address
+	});
+}
+
+//#endregion
+exports.fromUniswapToken = fromUniswapToken;
+exports.parse1cs = parse1cs;
+exports.stringify1cs = stringify1cs;

package/dist/index.d.cts

@@ -0,0 +1,23 @@
+//#region src/types.d.ts
+interface OneCsAsset {
+  version: "v1";
+  chain: string;
+  namespace: string;
+  reference: string;
+  selector?: string;
+}
+//#endregion
+//#region src/parse.d.ts
+declare function parse1cs(s: string): OneCsAsset;
+//#endregion
+//#region src/stringify.d.ts
+declare function stringify1cs(o: OneCsAsset): string;
+//#endregion
+//#region src/uniswap.d.ts
+interface UniToken {
+  chainId: number;
+  address: string;
+}
+declare function fromUniswapToken<T extends UniToken>(token: T, caip2slugMap?: Record<string, string>): string;
+//#endregion
+export { type OneCsAsset, UniToken, fromUniswapToken, parse1cs, stringify1cs };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+//#region src/types.d.ts
+interface OneCsAsset {
+  version: "v1";
+  chain: string;
+  namespace: string;
+  reference: string;
+  selector?: string;
+}
+//#endregion
+//#region src/parse.d.ts
+declare function parse1cs(s: string): OneCsAsset;
+//#endregion
+//#region src/stringify.d.ts
+declare function stringify1cs(o: OneCsAsset): string;
+//#endregion
+//#region src/uniswap.d.ts
+interface UniToken {
+  chainId: number;
+  address: string;
+}
+declare function fromUniswapToken<T extends UniToken>(token: T, caip2slugMap?: Record<string, string>): string;
+//#endregion
+export { type OneCsAsset, UniToken, fromUniswapToken, parse1cs, stringify1cs };

package/dist/index.js

@@ -0,0 +1,71 @@
+//#region 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",
+		chain,
+		namespace,
+		reference: decodeURIComponent(refEnc)
+	};
+	if (selEnc !== void 0) obj.selector = decodeURIComponent(selEnc);
+	return obj;
+}
+
+//#endregion
+//#region 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}`;
+}
+
+//#endregion
+//#region 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:143": "monad",
+	"eip155:196": "xlayer",
+	"eip155:8453": "base",
+	"eip155:36900": "adi",
+	"eip155:42161": "arbitrum",
+	"eip155:43114": "avalanche",
+	"eip155:80085": "berachain",
+	"eip155:9745": "plasma",
+	"eip155:534352": "scroll",
+	"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"
+};
+
+//#endregion
+//#region src/uniswap.ts
+const 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}`);
+	return stringify1cs({
+		version: "v1",
+		chain,
+		namespace: "erc20",
+		reference: token.address
+	});
+}
+
+//#endregion
+export { fromUniswapToken, parse1cs, stringify1cs };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "lampamazaza-new-crosschain-assetid",
+  "version": "1.1.2",
+  "private": false,
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/defuse-protocol/sdk-monorepo.git",
+    "directory": "packages/crosschain-assetid"
+  },
+  "bugs": {
+    "url": "https://github.com/defuse-protocol/sdk-monorepo/issues"
+  },
+  "homepage": "https://github.com/defuse-protocol/sdk-monorepo/tree/main/packages/crosschain-assetid#readme",
+  "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",
+    "tsdown": "0.19.0",
+    "typescript": "^5.4.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --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"
+	]
+}