amogus-sdk-crosschain-assetid 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +141 -0
  2. package/dist/index.cjs +80 -0
  3. package/dist/index.d.cts +23 -0
  4. package/dist/index.d.ts +23 -0
  5. package/dist/index.js +77 -0
  6. package/package.json +49 -0
  7. package/schemas/1cs_v1-object.schema.json +52 -0
  8. package/schemas/1cs_v1-string.schema.json +28 -0
package/README.md ADDED
@@ -0,0 +1,141 @@
1
+ # 1cs_v1 — Unified Cross-Chain Asset Identifier
2
+
3
+ ## Installation
4
+
5
+ ```bash
6
+ npm install amogus-sdk-crosschain-assetid
7
+ ```
8
+
9
+ ## Usage
10
+
11
+ ```typescript
12
+ import {parse1cs, stringify1cs} from 'amogus-sdk-crosschain-assetid';
13
+
14
+ const assetid = stringify1cs({
15
+ version: "v1",
16
+ chain: "eth",
17
+ namespace: "erc20",
18
+ reference: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
19
+ })
20
+
21
+ const obj = parse1cs("1cs_v1:eth:erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48")
22
+ ```
23
+
24
+ ## Purpose
25
+
26
+ `1cs_v1` is a **URL-safe, compact, human-readable** identifier format for
27
+ representing **any asset** (crypto token, NFT, native coin, wrapped/bridged asset,
28
+ or even fiat) **across chains** in a consistent way.
29
+
30
+ It is designed to:
31
+
32
+ - Let apps **refer to assets unambiguously** without chain-specific parsing logic.
33
+ - Work **cross-chain and cross-standard** — one format for EVM, Solana, Cosmos, NEAR,
34
+ Stellar, Aptos, Sui, fiat, etc.
35
+ - Be **safe in URLs, filenames, and APIs** without extra escaping.
36
+ - Enable **simple parsing** into an object with predictable fields.
37
+ - Serve as a **unified key** for balances, swaps, bridges, quotes, and off-ramps.
38
+
39
+ ---
40
+
41
+ ## Format
42
+
43
+ ```
44
+ 1cs_v1:<chain>:<namespace>:<reference>[:<selector>]
45
+ ```
46
+
47
+ ### Components
48
+
49
+ | Part | Required? | Description |
50
+ |---------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------|
51
+ | `1cs_v1` | ✅ | Format prefix and version. 1cs stands for [1ClickSwap](https://docs.near-intents.org/near-intents/integration/distribution-channels/1click-api). |
52
+ | `<chain>` | ✅ | Lowercase slug (e.g. `eth`, `eth-sepolia`, `solana`, `near`, `polygon`), can encode testnet in slug. |
53
+ | `<namespace>` | ✅ | Asset standard/kind: `erc20`, `erc721`, `spl`, `near-nft`, `aptos-coin`, `fiat`, etc. |
54
+ | `<reference>` | ✅ | Contract/mint/account/denom/issuer — **URI-encoded** to safely hold `:`, `/`, spaces, unicode, etc. |
55
+ | `<selector>` | optional | Sub-asset selector: token ID, module struct, Stellar code, etc. — also **URI-encoded**. |
56
+
57
+ ---
58
+
59
+ ## Examples
60
+
61
+ ### Fungible tokens
62
+
63
+ ```
64
+ 1cs_v1:eth:erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 # USDC on Ethereum
65
+ 1cs_v1:base:erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 # USDC on Base
66
+ 1cs_v1:fiat:iso4217:USD # US Dollar (fiat)
67
+ ```
68
+
69
+ ### NFTs
70
+
71
+ ```
72
+ 1cs_v1:eth:erc721:0x1234567890abcdef1234567890abcdef12345678:42
73
+ 1cs_v1:near:nep171:apes.coolnft.near:series%3A1%2Fblue%3A42
74
+ ```
75
+
76
+ ### Native coins
77
+
78
+ ```
79
+ 1cs_v1:eth:native:coin
80
+ 1cs_v1:zcash:native:coin
81
+ ```
82
+
83
+ ### Non-EVM standards
84
+
85
+ ```
86
+ 1cs_v1:solana:spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
87
+ 1cs_v1:aptos:aptos-coin:0x1%3A%3Aaptos_coin%3A%3AAptosCoin
88
+ ```
89
+
90
+ ---
91
+
92
+ ## Rationale & Design Choices
93
+
94
+ ### 1. URL safety
95
+
96
+ We encode `reference` and `selector` with `encodeURIComponent` so they are safe in URLs.
97
+
98
+ ### 2. Human-readable but unambiguous
99
+
100
+ - Prefix (`1cs_v1`) makes it clear what format is in use. Easy greppable across codebase.
101
+ - Chain slug + namespace covers most identification needs without extra lookups.
102
+ - Works for *both* blockchain and fiat.
103
+
104
+ ### 3. Multi-asset support
105
+
106
+ `selector` cleanly supports ERC-1155 IDs, Stellar asset codes, Cosmos token sub-denoms, Aptos/Sui struct names, etc.
107
+
108
+ ### 4. Bridged / wrapped assets
109
+
110
+ The ID identifies the *on-chain representation*. If you need to express the *origin*, bridge, issuer, or other
111
+ metadata — pass it as **query params** or in your object model, not in the core ID.
112
+
113
+ ---
114
+
115
+ ## Object Form
116
+
117
+ Parsing a `1cs_v1` string gives you:
118
+
119
+ ```ts
120
+ interface OneCsAsset {
121
+ version: "v1";
122
+ chain: string; // e.g. "eth", "near", "fiat"
123
+ namespace: string; // e.g. "erc20", "spl", "native"
124
+ reference: string; // decoded from URI
125
+ selector?: string; // decoded from URI if present
126
+ }
127
+ ```
128
+
129
+ Example:
130
+
131
+ ```
132
+ 1cs_v1:near:nep171:apes.coolnft.near:series%3A1%2Fblue%3A42
133
+ ↓
134
+ {
135
+ version: "v1",
136
+ chain: "near",
137
+ namespace: "nep171",
138
+ reference: "apes.coolnft.near",
139
+ selector: "series:1/blue:42"
140
+ }
141
+ ```
package/dist/index.cjs ADDED
@@ -0,0 +1,80 @@
1
+
2
+ //#region src/parse.ts
3
+ function parse1cs(s) {
4
+ const parts = s.split(":");
5
+ if (parts.length < 4 || parts.length > 5 || parts[0] !== "1cs_v1") throw new Error("Invalid 1cs_v1 string");
6
+ const [_, chain, namespace, refEnc, selEnc] = parts;
7
+ const obj = {
8
+ version: "v1",
9
+ chain,
10
+ namespace,
11
+ reference: decodeURIComponent(refEnc)
12
+ };
13
+ if (selEnc !== void 0) obj.selector = decodeURIComponent(selEnc);
14
+ return obj;
15
+ }
16
+
17
+ //#endregion
18
+ //#region src/stringify.ts
19
+ function stringify1cs(o) {
20
+ const ref = encodeURIComponent(o.reference);
21
+ const sel = o.selector != null ? `:${encodeURIComponent(o.selector)}` : "";
22
+ return `1cs_v1:${o.chain}:${o.namespace}:${ref}${sel}`;
23
+ }
24
+
25
+ //#endregion
26
+ //#region src/caip2-slug-registry.json
27
+ var caip2_slug_registry_default = {
28
+ "eip155:1": "eth",
29
+ "eip155:10": "optimism",
30
+ "eip155:56": "bsc",
31
+ "eip155:100": "gnosis",
32
+ "eip155:137": "polygon",
33
+ "eip155:143": "monad",
34
+ "eip155:196": "xlayer",
35
+ "eip155:8453": "base",
36
+ "eip155:36900": "adi",
37
+ "eip155:42161": "arbitrum",
38
+ "eip155:43114": "avalanche",
39
+ "eip155:80085": "berachain",
40
+ "eip155:9745": "plasma",
41
+ "eip155:534352": "scroll",
42
+ "bip122:000000000019d6689c085ae165831e93": "bitcoin",
43
+ "bip122:00040fe8ec8471911baa1db1266ea15d": "zcash",
44
+ "bip122:1a91e3dace36e2be3bf030a65679fe82": "doge",
45
+ "near:mainnet": "near",
46
+ "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "sol",
47
+ "tron:27Lqcw": "tron",
48
+ "xrpl:0": "xrpl",
49
+ "tvm:-239": "ton",
50
+ "sui:mainnet": "sui",
51
+ "aptos:mainnet": "aptos",
52
+ "stellar:pubnet": "stellar",
53
+ "cip34:1-764824073": "cardano",
54
+ "aleo:0": "aleo",
55
+ "bip122:00000ffd590b1485b3caadc19b22e637": "dash",
56
+ "eip155:2741": "abstract",
57
+ "starknet:SN_MAIN": "starknet",
58
+ "hlcore:mainnet": "hypercore",
59
+ "solana:CDLtwKnaCoK157uaHQDj4fHu72AyD251": "fogo"
60
+ };
61
+
62
+ //#endregion
63
+ //#region src/uniswap.ts
64
+ const evmSlugRegistry = caip2_slug_registry_default;
65
+ function fromUniswapToken(token, caip2slugMap) {
66
+ const caip2 = `eip155:${token.chainId}`;
67
+ const chain = caip2slugMap?.[caip2] ?? evmSlugRegistry[caip2];
68
+ if (chain == null) throw new Error(`Unsupported chainId = ${token.chainId}`);
69
+ return stringify1cs({
70
+ version: "v1",
71
+ chain,
72
+ namespace: "erc20",
73
+ reference: token.address
74
+ });
75
+ }
76
+
77
+ //#endregion
78
+ exports.fromUniswapToken = fromUniswapToken;
79
+ exports.parse1cs = parse1cs;
80
+ exports.stringify1cs = stringify1cs;
package/dist/index.d.cts ADDED
@@ -0,0 +1,23 @@
1
+ //#region src/types.d.ts
2
+ interface OneCsAsset {
3
+ version: "v1";
4
+ chain: string;
5
+ namespace: string;
6
+ reference: string;
7
+ selector?: string;
8
+ }
9
+ //#endregion
10
+ //#region src/parse.d.ts
11
+ declare function parse1cs(s: string): OneCsAsset;
12
+ //#endregion
13
+ //#region src/stringify.d.ts
14
+ declare function stringify1cs(o: OneCsAsset): string;
15
+ //#endregion
16
+ //#region src/uniswap.d.ts
17
+ interface UniToken {
18
+ chainId: number;
19
+ address: string;
20
+ }
21
+ declare function fromUniswapToken<T extends UniToken>(token: T, caip2slugMap?: Record<string, string>): string;
22
+ //#endregion
23
+ export { type OneCsAsset, UniToken, fromUniswapToken, parse1cs, stringify1cs };
package/dist/index.d.ts ADDED
@@ -0,0 +1,23 @@
1
+ //#region src/types.d.ts
2
+ interface OneCsAsset {
3
+ version: "v1";
4
+ chain: string;
5
+ namespace: string;
6
+ reference: string;
7
+ selector?: string;
8
+ }
9
+ //#endregion
10
+ //#region src/parse.d.ts
11
+ declare function parse1cs(s: string): OneCsAsset;
12
+ //#endregion
13
+ //#region src/stringify.d.ts
14
+ declare function stringify1cs(o: OneCsAsset): string;
15
+ //#endregion
16
+ //#region src/uniswap.d.ts
17
+ interface UniToken {
18
+ chainId: number;
19
+ address: string;
20
+ }
21
+ declare function fromUniswapToken<T extends UniToken>(token: T, caip2slugMap?: Record<string, string>): string;
22
+ //#endregion
23
+ export { type OneCsAsset, UniToken, fromUniswapToken, parse1cs, stringify1cs };
package/dist/index.js ADDED
@@ -0,0 +1,77 @@
1
+ //#region src/parse.ts
2
+ function parse1cs(s) {
3
+ const parts = s.split(":");
4
+ if (parts.length < 4 || parts.length > 5 || parts[0] !== "1cs_v1") throw new Error("Invalid 1cs_v1 string");
5
+ const [_, chain, namespace, refEnc, selEnc] = parts;
6
+ const obj = {
7
+ version: "v1",
8
+ chain,
9
+ namespace,
10
+ reference: decodeURIComponent(refEnc)
11
+ };
12
+ if (selEnc !== void 0) obj.selector = decodeURIComponent(selEnc);
13
+ return obj;
14
+ }
15
+
16
+ //#endregion
17
+ //#region src/stringify.ts
18
+ function stringify1cs(o) {
19
+ const ref = encodeURIComponent(o.reference);
20
+ const sel = o.selector != null ? `:${encodeURIComponent(o.selector)}` : "";
21
+ return `1cs_v1:${o.chain}:${o.namespace}:${ref}${sel}`;
22
+ }
23
+
24
+ //#endregion
25
+ //#region src/caip2-slug-registry.json
26
+ var caip2_slug_registry_default = {
27
+ "eip155:1": "eth",
28
+ "eip155:10": "optimism",
29
+ "eip155:56": "bsc",
30
+ "eip155:100": "gnosis",
31
+ "eip155:137": "polygon",
32
+ "eip155:143": "monad",
33
+ "eip155:196": "xlayer",
34
+ "eip155:8453": "base",
35
+ "eip155:36900": "adi",
36
+ "eip155:42161": "arbitrum",
37
+ "eip155:43114": "avalanche",
38
+ "eip155:80085": "berachain",
39
+ "eip155:9745": "plasma",
40
+ "eip155:534352": "scroll",
41
+ "bip122:000000000019d6689c085ae165831e93": "bitcoin",
42
+ "bip122:00040fe8ec8471911baa1db1266ea15d": "zcash",
43
+ "bip122:1a91e3dace36e2be3bf030a65679fe82": "doge",
44
+ "near:mainnet": "near",
45
+ "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "sol",
46
+ "tron:27Lqcw": "tron",
47
+ "xrpl:0": "xrpl",
48
+ "tvm:-239": "ton",
49
+ "sui:mainnet": "sui",
50
+ "aptos:mainnet": "aptos",
51
+ "stellar:pubnet": "stellar",
52
+ "cip34:1-764824073": "cardano",
53
+ "aleo:0": "aleo",
54
+ "bip122:00000ffd590b1485b3caadc19b22e637": "dash",
55
+ "eip155:2741": "abstract",
56
+ "starknet:SN_MAIN": "starknet",
57
+ "hlcore:mainnet": "hypercore",
58
+ "solana:CDLtwKnaCoK157uaHQDj4fHu72AyD251": "fogo"
59
+ };
60
+
61
+ //#endregion
62
+ //#region src/uniswap.ts
63
+ const evmSlugRegistry = caip2_slug_registry_default;
64
+ function fromUniswapToken(token, caip2slugMap) {
65
+ const caip2 = `eip155:${token.chainId}`;
66
+ const chain = caip2slugMap?.[caip2] ?? evmSlugRegistry[caip2];
67
+ if (chain == null) throw new Error(`Unsupported chainId = ${token.chainId}`);
68
+ return stringify1cs({
69
+ version: "v1",
70
+ chain,
71
+ namespace: "erc20",
72
+ reference: token.address
73
+ });
74
+ }
75
+
76
+ //#endregion
77
+ export { fromUniswapToken, parse1cs, stringify1cs };
package/package.json ADDED
@@ -0,0 +1,49 @@
1
+ {
2
+ "name": "amogus-sdk-crosschain-assetid",
3
+ "version": "1.7.0",
4
+ "private": false,
5
+ "type": "module",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/defuse-protocol/sdk-monorepo.git",
9
+ "directory": "packages/crosschain-assetid"
10
+ },
11
+ "bugs": {
12
+ "url": "https://github.com/defuse-protocol/sdk-monorepo/issues"
13
+ },
14
+ "homepage": "https://github.com/defuse-protocol/sdk-monorepo/tree/main/packages/crosschain-assetid#readme",
15
+ "sideEffects": false,
16
+ "main": "./dist/index.cjs",
17
+ "module": "./dist/index.js",
18
+ "types": "./dist/index.d.ts",
19
+ "exports": {
20
+ ".": {
21
+ "import": {
22
+ "types": "./dist/index.d.ts",
23
+ "default": "./dist/index.js"
24
+ },
25
+ "require": {
26
+ "types": "./dist/index.d.cts",
27
+ "default": "./dist/index.cjs"
28
+ }
29
+ },
30
+ "./schemas/1cs_v1-object.schema.json": "./schemas/1cs_v1-object.schema.json",
31
+ "./schemas/1cs_v1-string.schema.json": "./schemas/1cs_v1-string.schema.json"
32
+ },
33
+ "files": [
34
+ "dist",
35
+ "schemas"
36
+ ],
37
+ "scripts": {
38
+ "build": "tsdown",
39
+ "dev": "tsdown --watch",
40
+ "lint": "biome check .",
41
+ "format": "biome format --write .",
42
+ "typecheck": "tsc --noEmit"
43
+ },
44
+ "devDependencies": {
45
+ "ajv": "^8.17.1",
46
+ "tsdown": "0.19.0",
47
+ "typescript": "^5.4.2"
48
+ }
49
+ }
package/schemas/1cs_v1-object.schema.json ADDED
@@ -0,0 +1,52 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://example.com/1cs_v1-object.schema.json",
4
+ "title": "1cs_v1 asset (object form, encodeURIComponent on stringify)",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "properties": {
8
+ "version": {
9
+ "const": "v1"
10
+ },
11
+ "chain": {
12
+ "type": "string",
13
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
14
+ },
15
+ "namespace": {
16
+ "type": "string",
17
+ "pattern": "^[a-z][a-z0-9-]*$"
18
+ },
19
+ "reference": {
20
+ "type": "string",
21
+ "minLength": 1,
22
+ "description": "RAW (decoded) value; will be encodeURIComponent()'d when stringified."
23
+ },
24
+ "selector": {
25
+ "type": "string",
26
+ "minLength": 1,
27
+ "description": "RAW (decoded) sub-id; will be encodeURIComponent()'d when stringified."
28
+ }
29
+ },
30
+ "required": ["version", "chain", "namespace", "reference"],
31
+ "examples": [
32
+ {
33
+ "version": "v1",
34
+ "chain": "eth",
35
+ "namespace": "erc20",
36
+ "reference": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
37
+ },
38
+ {
39
+ "version": "v1",
40
+ "chain": "near",
41
+ "namespace": "near-nft",
42
+ "reference": "apes.coolnft.near",
43
+ "selector": "series.1:blue/42"
44
+ },
45
+ {
46
+ "version": "v1",
47
+ "chain": "fiat",
48
+ "namespace": "iso4217",
49
+ "reference": "EUR"
50
+ }
51
+ ]
52
+ }
package/schemas/1cs_v1-string.schema.json ADDED
@@ -0,0 +1,28 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://example.com/1cs_v1-string.schema.json",
4
+ "title": "1cs_v1 asset ID (string, URI-component encoding)",
5
+ "type": "string",
6
+ "$defs": {
7
+ "uriComponent": {
8
+ "type": "string",
9
+ "pattern": "^(?:[A-Za-z0-9\\-_.!~*'()]|%[0-9A-Fa-f]{2})+$"
10
+ },
11
+ "chain": {
12
+ "type": "string",
13
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
14
+ },
15
+ "namespace": {
16
+ "type": "string",
17
+ "pattern": "^[a-z][a-z0-9-]*$"
18
+ }
19
+ },
20
+ "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})+)?$",
21
+ "examples": [
22
+ "1cs_v1:eth:erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
23
+ "1cs_v1:eth-sepolia:erc721:0xAbcDEF1234567890abcdef1234567890ABCDef12:42",
24
+ "1cs_v1:near:near-nft:apes.coolnft.near:series.1%3Ablue%2F42",
25
+ "1cs_v1:aptos:aptos-coin:0x1%3A%3Aaptos_coin%3A%3AAptosCoin",
26
+ "1cs_v1:fiat:iso4217:EUR"
27
+ ]
28
+ }