# @defuse-protocol/crosschain-assetid 中文文档

规范地址：https://npmcn.com/package/%40defuse-protocol/crosschain-assetid/

版本：1\.15\.0
npm 元数据更新时间：2026-10-23T15:09:45.119Z
中文译文更新时间：2026-11-11T21:16:19.120Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40defuse-protocol/crosschain-assetid
原文对照：https://npmcn.com/package/%40defuse-protocol/crosschain-assetid/?lang=original
项目主页：https://github.com/defuse-protocol/sdk-monorepo/tree/main/packages/crosschain-assetid#readme
源码仓库：https://github.com/defuse-protocol/sdk-monorepo

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：16 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-09-10T13:37:47.779Z
- 最新版本发布：2026-10-23T15:09:44.659Z
- 近 30 天下载量：5351（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 19 个）

## 中文简介

`bash npm install @defuse-protocol/crosschain-assetid`

## 安装

```sh
npm install @defuse-protocol/crosschain-assetid
```

也可以使用：`pnpm add @defuse-protocol/crosschain-assetid`、`yarn add @defuse-protocol/crosschain-assetid`、`bun add @defuse-protocol/crosschain-assetid`

## README

# 1cs v1 — 统一跨天资产标识符

## 安装

```bash
npm install @defuse-protocol/crosschain-assetid
```

## 使用量

```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")
```

## 目的

`1cs_v1` 是一个 **URL -- -- 安全、紧凑、人可读** 标识符格式 代表 **任何资产** (crypto sord, NFT, 土生土长的硬币,被包裹/被压缩的资产, 或甚至没有) **跨链条** 以一贯的方式.

其目的是:

-   让应用 **明确提及资产** 而不包含特定链解析逻辑.
-   工作 **跨链和跨标准** - EVM、索拉纳、宇宙、NEAR、, 史黛拉,阿普托斯,苏伊,费亚特等.
-   成为 **在 URL、文件名和 API 中安全** 没有额外逃出.
-   启用 **简单解析** 以可预见字段为对象.
-   做一个 **统一密钥** 平衡,交换,桥梁,引文,和离线.

* * *

## 格式

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

### 构成部分

| 编 | 需要吗? | 说明 |
| --- | --- | --- |
| `1cs_v1` | ✅ | 格式化前缀和版本. 1克代表着 [1 分块](https://docs.near-intents.org/near-intents/integration/distribution-channels/1click-api)。 。 。 . |
| `<chain>` | ✅ | 小写弹道( 如 . `eth`, (中文(简体) ), `eth-sepolia`, (中文(简体) ), `solana`, (中文(简体) ), `near`, (中文(简体) ), `polygon`),可以将测试网编码为sult. |
| `<namespace>` | ✅ | 资产标准/实物: `erc20`, (中文(简体) ), `erc721`, (中文(简体) ), `spl`, (中文(简体) ), `near-nft`, (中文(简体) ), `aptos-coin`, (中文(简体) ), `aptos-fa`, (中文(简体) ), `fiat`等 (中文(简体) ). |
| `<reference>` | ✅ | 合同/薄荷/账户/帐号/签发人- **URI 编码** 安全持有 `:`, (中文(简体) ), `/`空格 单码等. |
| `<selector>` | 选项 | 子资产选择器:代号ID,模块struct,Stellar代码等——也 **URI 编码**。 。 。 . |

* * *

## 实例

### 易打符号

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

### 无

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

### 原生硬币

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

### 非EVM标准

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

Aptos有两个可互换的标准,所以 `reference` 每个形状不同 :

-   `aptos-coin` 遗产 `Coin<T>` 标准. `reference` 是完全合格的移动结构类型( T)`address::module::Struct`) (中文(简体) ).
-   `aptos-fa` ——可交易资产标准[AIP-21 (英语)](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-021-fungible-assets.md)) (中文(简体) ). `reference` 是一个普通对象地址,但 `0x1::fungible_asset::Metadata` 资源.

* * *

## 理由和设计选择

### 1\. URL安全

我们编码 `reference` 财务报告和审定财务报表 `selector` 与 `encodeURIComponent` 因此,他们是安全的在URL.

### 2\. 人可读而毫不含糊

-   前缀( E)`1cs_v1`),明确使用什么格式. 轻而易举地穿过密码基地.
-   链状弹壳+命名空间覆盖大多数识别需求而无需额外查找.
-   工程为 _两者_ 断层链和花纹.

### 3\. 多资产支助

`selector` 干净地支持 ERC-1155 ID, Stellar 资产代码, Cosmos sident sub-denoms, Aptos/Sui struct names等.

### 4\. 搭桥/包头资产

身份证识别 _链上代表_如果您需要表达 _来源_、桥梁、发行人或其他 元数据——通过 **查询段落** 或在其对象模型中,而不是在核心ID中.

* * *

## 对象窗体

分析a `1cs_v1` 字符串给你:

```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
}
```

示例

```
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"
}
```

## 常见问题

### @defuse-protocol/crosschain-assetid 是什么？

bash npm install @defuse-protocol/crosschain-assetid

### 如何安装 @defuse-protocol/crosschain-assetid？

在项目目录运行 npm install @defuse-protocol/crosschain-assetid，或使用 pnpm add / yarn add / bun add。

### @defuse-protocol/crosschain-assetid 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @defuse-protocol/crosschain-assetid 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @defuse-protocol/crosschain-assetid 可以商用吗？

@defuse-protocol/crosschain-assetid 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @defuse-protocol/crosschain-assetid 的下载量有多少？

根据 npm 官方下载统计，@defuse-protocol/crosschain-assetid 在 2026/10/12 – 2026/11/10 这 30 天内被下载 5,351 次，日均约 178 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @defuse-protocol/crosschain-assetid 还在维护吗？

最新版本 1\.15\.0 发布于 2026/10/23（19 天前）；至今共发布 22 个版本，其中过去 12 个月发布了 19 个；首次发布于 2025/09/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。