# @celo/attribution-tags 中文文档

规范地址：https://npmcn.com/package/%40celo/attribution-tags/

版本：0\.5\.0
npm 元数据更新时间：2026-09-21T09:24:23.674Z
中文译文更新时间：2026-11-09T08:18:33.288Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40celo/attribution-tags
原文对照：https://npmcn.com/package/%40celo/attribution-tags/?lang=original
项目主页：https://github.com/celo-org/attribution-tags#readme
源码仓库：https://github.com/celo-org/attribution-tags

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

- 包体积（解压后）：56.7 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- peer 依赖：viem ^2
- 首次发布：2026-07-01T14:38:56.784Z
- 最新版本发布：2026-09-21T09:24:23.249Z
- 近 30 天下载量：3587（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

ERC-8021 为Celo的归属. 一行标记和校验 在牛上.

## 安装

```sh
npm install @celo/attribution-tags
```

也可以使用：`pnpm add @celo/attribution-tags`、`yarn add @celo/attribution-tags`、`bun add @celo/attribution-tags`

## README

# @ celo/ 归属标签

ERC-8021 归属 **赛罗岛**。一行用于标记交易;一行用于验证交易。 环绕 [`ox/erc8021`](https://oxlib.sh/ercs/erc8021/Attribution)。 。 。 .

按优先秩序为:

1.  **微费** 应用程序
2.  **船舶证明** 组群项目
3.  **Celo生态系统** 范围更广的项目

SDK 仅为 Celo —— 低于全部使用的例子 `viem/chains`是因为 `celo` 编号 : `celoSepolia`配置您的viem客户端.

## 安装

```bash
npm install @celo/attribution-tags viem
# or
pnpm add @celo/attribution-tags viem
# or
yarn add @celo/attribution-tags viem
```

`viem` 是一个可选的对等端 dep,只有在您呼叫时需要 `verifyTx` 或用途 `withAttribution`。 。 。 .

> **未公布的本地测试 :** `cd sdk && npm pack` 生成一个 `.tgz` 您可以安装 `npm install /absolute/path/to/celo-attribution-tags-X.Y.Z.tgz` (或 `pnpm add /path/...tgz`) (中文(简体) ). 路径是绝对的并针对机器的,因此这只用于本地工作流程;用于跨机共享,从npm安装.

## 使用量

### 标记每笔交易( 建议)

扩展钱包客户端一次; 每一次 `sendTransaction`, (中文(简体) ), `writeContract` (和 `*Sync`) 称其为带后缀,包括没有的纯值转移 `data`数字 :

```ts
import { withAttribution } from "@celo/attribution-tags";
import { createWalletClient, http } from "viem";
import { celo } from "viem/chains";

const wallet = createWalletClient({ chain: celo, transport: http() })
  .extend(withAttribution("celo_b7k3p9da"));

await wallet.sendTransaction({ to: "0x...", value: 0n });
await wallet.writeContract({ address, abi, functionName: "transfer", args });
```

如果数据已经以 Schema 0 标记结束, 代码将被合并为一个后缀( 无双标记); Schema 2 标记没有被更改 。 电话站 `dataSuffix` 放在归属标记之前. `sendCalls` (EIP-5792)没有包裹——使用viem 2.45的客户端级别 `dataSuffix` 选择.

### 标记单个交易

```ts
import { toDataSuffix } from "@celo/attribution-tags";
import { createWalletClient, http } from "viem";
import { celo } from "viem/chains";

const wallet = createWalletClient({ chain: celo, transport: http() });

await wallet.sendTransaction({
  to: "0x...",
  value: 0n,
  data: toDataSuffix("celo_b7k3p9da"),
});
```

**关于多码的说明 :** ERC-8021让一个后缀带有几个代码—— `toDataSuffix(["foo", "bar"])` 由线条格式支持。 但每个代码只能由它所代表的实体添加. 您的应用程序发布自己的代码; 平台代码如 `minipay` 由平台的钱包添加,而不是由您的应用程序添加. 见 [`BUILDERS.md`](https://npmcn.com/package/%40celo/BUILDERS.md) 对于全层规则.

### 验证交易

```ts
import { verifyTx } from "@celo/attribution-tags";
import { createPublicClient, http } from "viem";
import { celo } from "viem/chains";

const client = createPublicClient({ chain: celo, transport: http() });

const result = await verifyTx({ client, hash: "0x..." });
// → { codes: ["celo_b7k3p9da"], schemaId: 0 } or null
```

### 智能账户交易(ERC-4337)

当用户有智能合同钱包时,链上交易是捆绑商的 `handleOps` 调用 EntryPoint , 应用程序的后缀位于用户操作的内部 `callData`。 。 。 . `verifyTx` 自动处理此选项( EntryPoint v. 6. 6和v. 7): 如果外部输入没有标记, 它解码捆绑并返回第一个被标记的操作, 用 `sender` 设置到生成它的智能账户。 要看到每个操作:

```ts
import { verifyUserOps, fromEntryPointCalldata } from "@celo/attribution-tags";

await verifyUserOps({ client, hash });
// → [{ sender: "0xad00…", attribution: { codes: ["celo_b7k3p9da"], schemaId: 0 } }, …]
//   or null if the tx is not a handleOps bundle

fromEntryPointCalldata(tx.input); // same, offline, from raw calldata
```

信贷 `sender`,而不是交易的 `from` —— 说 `from` 是捆绑者.

### 解码后缀下线

```ts
import { fromDataSuffix } from "@celo/attribution-tags";

fromDataSuffix("0x63656c6f040080218021802180218021802180218021");
// → { codes: ["celo"], schemaId: 0 }
```

### 基于作用的标签(Schema 2)——用于促进者和支付基础设施

ERC-8021 Schema 2 编码 _谁扮演的角色_ 生成交易,而不是一个平面代码列表。 是支付促进者(如x402结算服务)使用的形状,代表一个应用提交交易,并想将应用,促进者,以及可选择的支付客户端分别归属:

```ts
import { toRoleDataSuffix } from "@celo/attribution-tags";

const suffix = toRoleDataSuffix({
  app: "celo_b7k3p9da",   // the app / resource server
  wallet: "celo_facil",   // the wallet / facilitator submitting the tx
  service: "celo_agent",  // optional: the paying client
});
// append to settlement calldata: concat([callData, suffix])
```

`fromDataSuffix` 编号 : `verifyTx` 自动解码 Schema 2 :

```ts
fromDataSuffix(suffix);
// → {
//     codes: ["celo_b7k3p9da", "celo_facil", "celo_agent"],
//     schemaId: 2,
//     app: "celo_b7k3p9da",
//     wallet: "celo_facil",
//     service: ["celo_agent"],
//   }
```

大多数应用程序不需要这个: 如果你正在标记自己的交易, 请使用 `toDataSuffix` (Schema 0) (英语). Schema 2 用于提交交易的基础设施 _页:1_ 别人.

## 线条格式

**示马 0** (默认——) `toDataSuffix`) (中文(简体) ). 后缀布局,在调用数据结尾读取从左到右:

```
[code:N][length:1][schema:1][marker:16]
                      0x00     0x80218021…×8
```

多码被编码为代码域中被逗号限定的字符串;SDK在解码上被分出.

**示马 2** (基于作用-) `toRoleDataSuffix`:

```
[CBOR map {a,w,s}][length:2][schema:1][marker:16]
                               0x02      0x80218021…×8
```

CBOR地图使用ERC-8021的犬形短键: `a` =应用代码, `w` =钱包代码, `s` =服务代码(阵列). 编码授权给 `ox/erc8021`,因此它与Schema 2的其他执行是线相容的.

标记常数导出为 `ERC_8021_MARKER`。 。 。 .

## 验证

`toDataSuffix` 财务报告和审定财务报表 `toRoleDataSuffix` 拒绝代码:

-   空或大于 32 字节
-   包含任何外部 `[a-z0-9_]` (没有大写,没有空格,没有逗号)
-   逗号相接, 共超过 255 字节( 线条格式的长度字节会盖多码字段)

这比ERC-8021本身更严格,但与Celo分发的格式相匹配(`celo_xxxxxxxx`和Celo生态系统使用的平台代码(`minipay`, (中文(简体) ), `proofofship`) (中文(简体) ). 在这些界限内,任何代码的作品—— 发布,主机名衍生, 或者你为您的应用程序选择的自定义.

## API 密码

```ts
toDataSuffix(code: string | readonly string[]): Hex          // Schema 0
toRoleDataSuffix({ app?, wallet?, service? }): Hex            // Schema 2
withAttribution(code | codes): (client) => client   // viem wallet-client extension
fromDataSuffix(data: Hex): DecodedSuffix | null
verifyTx({ client, hash }): Promise<DecodedSuffix | null>
verifyUserOps({ client, hash }): Promise<UserOpAttribution[] | null>   // ERC-4337 bundles
fromEntryPointCalldata(data: Hex): UserOpAttribution[] | null          // offline variant
codeFromHostname(hostname: string): string  // → "celo_" + 12 hex chars
codeFromRepo(repo: string): string          // → "celo_" + 12 hex chars ("owner/repo" or github.com URL)

interface DecodedSuffix {
  codes: string[];      // every code found, regardless of schema
  schemaId: number;     // 0 or 2
  app?: string;         // Schema 2 only
  wallet?: string;      // Schema 2 only
  service?: string[];   // Schema 2 only
  sender?: `0x${string}`; // ERC-4337 only: the smart account to credit
}

interface UserOpAttribution {
  sender: `0x${string}`;              // UserOperation sender (smart account)
  attribution: DecodedSuffix | null;  // null if that op is untagged
}

ENTRY_POINT_ADDRESSES: { v0_6: `0x${string}`; v0_7: `0x${string}` }  // canonical EntryPoints

type AttributionTagSuffix = Hex  // alias for the suffix return type
ERC_8021_MARKER: "0x80218021802180218021802180218021"
```

`fromDataSuffix` 接受完整的 calldata,而不只是赤裸的后缀——它从结尾来描述. 它回来了 `null` 任何不是干净的 Schema 0 或 Schema 2 标记: 没有标记、 Schema 1( 海关- 注册) 标记, 或根本没有代码的标记 .

`withAttribution(code)` 返回viem `extend` 函数。 它在构建时验证代码一次( 在发送任何交易之前, 将代码扔入无效代码) 并包 `sendTransaction`, (中文(简体) ), `sendTransactionSync`, (中文(简体) ), `writeContract` 财务报告和审定财务报表 `writeContractSync` 当客户拥有他们。 SDK仍然不导入viem:扩展是结构上输入的,因此你的客户端保留了viem自己的类型.

`verifyTx` 从不扔出 — RPC 错误返回 `null`用于 ERC-4337 捆绑(`handleOps` 在 EntextPoint v. 6 或 v. 7 上, 由选择器检测到的, 故 EntersPoint 部署工作也在进行中) 它会回到每个用户操作的解码 `callData` 并返回第一个带有标签的 `sender`。 。 。 . `verifyUserOps` 返回所有操作.

`codeFromHostname` 从主机名中获取一个每个应用程序代码( MiniPay 迷你应用程序使用, 无需注册步骤即可自行属性) 。 算法:小写 = 条形引线 `www.` — SHA-256 — 前6个字节( 12个字节) — `celo_` 前缀。 相同的输入 – 相同的代码,每次都如此.

`codeFromRepo` 复制了 Celo Builders 平台从它的 GitHub 寄存器中衍生出项目代码,因此建设者可以断言其配置中的代码与自己的寄存器相匹配. 算法:修饰-小写-SHA-256 `owner/repo` 击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击 `celo_` 前缀。 满 `https://github.com/owner/repo` URL( 有无) `.git` / 后行路径)被降低为先被弹出. 任何没有的 `owner/repo` 掷出.

### 固定主机名 ~ 代码向量

独立核查 `shasum -a 256` 和反对 [`tests/hostname.test.ts`](https://npmcn.com/package/%40celo/attribution-tags/tests/hostname.test.ts)。如果重新执行不产生这些值,算法已经漂移了.

| 主机名 | 代码 |
| --- | --- |
| `mondeto.app` | `celo_b057492a5aa5` |
| `celo.org` | `celo_8549372f8229` |
| `minipay.io` | `celo_51e519342b9a` |
| `app.mondeto.app` | `celo_1a8ba29dac7a` |
| `mondeto.vercel.app` | `celo_04168799c492` |

子域在设计上保持不变(因此) `*.vercel.app` 应用程序并非全部拼接成一个代码). 预览/中继主机名称因此产生自己的代码;在仪表板层的集合环境,而不是SDK层.

### 固定寄存器 = 代码向量

反对 `shasum -a 256` 和反对 [`tests/repo.test.ts`](https://npmcn.com/package/%40celo/attribution-tags/tests/repo.test.ts),也可以比较 `codeFromRepo` 以及每跑一次的月台衍生内容的逐字记录.

| 仓库 | 代码 |
| --- | --- |
| `gigahierz/trading-bot-updown` | `celo_7b3c251337be` |
| `icmelvin/myceloproject` | `celo_4d19a013cc70` |
| `icmelvin/2nd-celo-hackathon` | `celo_3712ca0f1cdc` |

大小写和周围的白色空间不重要(`icmelvin/MyCeloProject` 给与相同的代码;寄存器名称确实——叉子或更名的repo是一个不同的代码.

## 许可证

麻省理工学院.

## 常见问题

### @celo/attribution-tags 是什么？

ERC-8021 为Celo的归属\. 一行标记和校验 在牛上\.

### 如何安装 @celo/attribution-tags？

在项目目录运行 npm install @celo/attribution-tags，或使用 pnpm add / yarn add / bun add。

### @celo/attribution-tags 支持 TypeScript 吗？

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

### @celo/attribution-tags 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @celo/attribution-tags 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @celo/attribution-tags 可以商用吗？

@celo/attribution-tags 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @celo/attribution-tags 的下载量有多少？

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

### @celo/attribution-tags 还在维护吗？

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