# @ethereum-sourcify/lib-sourcify 中文文档

规范地址：https://npmcn.com/package/%40ethereum-sourcify/lib-sourcify/

版本：3\.8\.0
npm 元数据更新时间：2026-11-03T07:43:21.937Z
中文译文更新时间：2026-11-13T23:40:22.155Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.3 MB，132 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：v26\.10\.0
- 运行依赖：6 个
- 首次发布：2023-03-13T08:19:22.202Z
- 最新版本发布：2026-11-03T07:43:21.767Z
- 近 30 天下载量：40590（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：67（近 12 个月 19 个）

## 中文简介

苏中合同核查方法库,合同验证,类型,界面.

## 安装

```sh
npm install @ethereum-sourcify/lib-sourcify
```

也可以使用：`pnpm add @ethereum-sourcify/lib-sourcify`、`yarn add @ethereum-sourcify/lib-sourcify`、`bun add @ethereum-sourcify/lib-sourcify`

## README

# lib- surcify v2 (中文(简体) )

[![codecov](https://codecov.io/gh/argotorg/sourcify/branch/staging/graph/badge.svg?token=eN6XDAwWfV&flag=lib-sourcify)](https://codecov.io/gh/argotorg/sourcify)

lib -surcify 是 (英语) [强制化](https://sourcify.dev/)用于验证合同的可重用的主干线库。 版本2引入了经过完善抽象的完全重新设计的架构,更好地支持Solity和Vyper合同,更加灵活的验证过程,以及浏览器支持.

## 概览

lib-sourcify提供了验证,编译和验证智能合同的工具.

库支持使用 Solidity 元数据.json 和 Solidity 和 Vyper 的标准-JSON 输入格式进行校验

## 安装

```bash
npm install @ethereum-sourcify/lib-sourcify
```

## 快速启动

```typescript
import {
  SolidityCompilation,
  Verification,
  SourcifyChain,
  ISolidityCompiler,
  SolidityJsonInput,
  SolidityOutput,
} from '@ethereum-sourcify/lib-sourcify';
import { useSolidityCompiler } from '@ethereum-sourcify/compilers';
import * as fs from 'fs';

// Step 1: Setup your compiler
class Solc implements ISolidityCompiler {
  private solcRepoPath: string;
  private solJsonRepoPath: string;

  constructor(solcRepoPath: string, solJsonRepoPath: string) {
    this.solcRepoPath = solcRepoPath;
    this.solJsonRepoPath = solJsonRepoPath;
  }

  async compile(
    version: string,
    solcJsonInput: SolidityJsonInput,
    forceEmscripten: boolean = false,
  ): Promise<SolidityOutput> {
    return await useSolidityCompiler(
      this.solcRepoPath, // useSolidityCompiler will automatically download and store solc here
      this.solJsonRepoPath, // useSolidityCompiler will automatically download and store solcjs here
      version,
      solcJsonInput,
      forceEmscripten,
    );
  }
}

const solc = new Solc('/path/to/solc', '/path/to/solcjs');

// Step 2: Prepare your standard JSON input
const jsonInput = {
  language: 'Solidity',
  sources: {
    'Contract.sol': {
      content: 'contract MyContract { function foo() public {} }',
    },
  },
  settings: {
    optimizer: {
      enabled: true,
      runs: 200,
    },
    outputSelection: {
      '*': [],
    },
  },
} as SolidityJsonInput;

// Step 3: Create a compilation
const compilation = new SolidityCompilation(
  solc,
  '0.8.20', // compiler version
  jsonInput,
  {
    path: 'Contract.sol',
    name: 'MyContract', // The name of your contract
  },
);

// Step 4: Set up a SourcifyChain instance
const myChain = new SourcifyChain({
  name: 'My EVM Chain',
  chainId: 1337,
  rpc: ['http://localhost:8545'],
  supported: true,
});

// Step 5: Verify the contract
const verification = new Verification(
  compilation,
  myChain,
  '0xc0ffee254729296a45a3885639AC7E10F9d54979',
);

await verification.verify();

// Step 6: Check verification status
console.log(verification.status); // { runtimeMatch: 'perfect', creationMatch: null }
```

这个例子显示了使用标准JSON输入的固态合同的完整验证流程. 关于Vyper合同或更先进的使用案例,见下文详细章节.

## 在浏览器中使用

对于浏览器的使用,我们建议使用 [网络索尔c](https://github.com/gnidan/web-solc) 改为 `@ethereum-sourcify/compilers`。这里是一个如何执行 `ISolidityCompiler` 接口 `web-solc`数字 :

```typescript
import {
  ISolidityCompiler,
  SolidityJsonInput,
} from '@ethereum-sourcify/lib-sourcify';
import { fetchSolc } from 'web-solc';

class Solc implements ISolidityCompiler {
  async compile(
    version: string,
    solcJsonInput: SolidityJsonInput,
  ): Promise<any> {
    const { compile } = await fetchSolc(version);
    return await compile(solcJsonInput);
  }
}

const solc = new Solc();
```

## 建筑

lib-surcify v2由几个关键组件组成:

-   **验证**:基于一个 Solidity 元数据.json 文件描述合同构建,检查所有源文件是否都存在并有效. 必要时从 IPFS 中获取缺失的来源 .
    
    -   `SolidityMetadataContract`: 与元数据和源文件的团结合同
    -   `processFiles.ts`: 用于创建的工具函数 `SolidityMetadataContract` 来自文件的实例
-   **汇编**: 处理合同汇编
    
    -   `AbstractCompilation`: 编译的基础类
    -   `SolidityCompilation`: 处理固态汇编
    -   `VyperCompilation`: 处理 Vyper 编译
-   **钉死钱**: 处理块链交互, 如获取字节代码和交易数据
    
-   **核查**: 比较编译的字节代码 `Compilation` 带有一个链上字节代码 `SourcifyChain`
    
    -   `Verification`: 主持核查进程的主要班级

## 配置

### RPC 超时配置

您可以通过 `SourcifyChain` 类 :

```typescript
import { SourcifyChain } from '@ethereum-sourcify/lib-sourcify';

// Set global RPC timeout to 30 seconds
SourcifyChain.setGlobalRpcTimeout(30 * 1000);

// Get the current global RPC timeout
const timeout = SourcifyChain.getGlobalRpcTimeout(); // Default is 10 seconds
```

### IPFS 网关配置

您可以配置用于获取缺失源的 IPFS 网关 :

```typescript
import { SolidityMetadataContract } from '@ethereum-sourcify/lib-sourcify';

// Set a custom IPFS gateway
SolidityMetadataContract.setGlobalIpfsGateway({
  url: 'https://my-ipfs-gateway.com/ipfs/',
  headers: { Authorization: 'Bearer my-token' },
});

// Get the current IPFS gateway configuration
const gateway = SolidityMetadataContract.getGlobalIpfsGateway();
```

### 日志配置

您可以设置全局日志级别并提供自定义日志 :

```typescript
import {
  setLibSourcifyLoggerLevel,
  setLibSourcifyLogger,
  getLibSourcifyLoggerLevel,
} from '@ethereum-sourcify/lib-sourcify';

// Set the log level
setLibSourcifyLoggerLevel(5); // 0=errors, 1=warnings, 2=info, 5=debug, 6=silly

// Get the current log level
const logLevel = getLibSourcifyLoggerLevel();

// Use a custom logger
setLibSourcifyLogger({
  logLevel: 2,
  setLevel(level: number) {
    this.logLevel = level;
  },
  log(level, msg) {
    // Custom logging implementation
  },
});
```

## 编译器设置

这个 `lib-sourcify` 库中不包含编译器作为依赖。 相反,你需要提供一个类 执行任何一种 `ISolidityCompiler` 或者说 `IVyperCompiler` 界面并传递给需要编译器的任何函数。 我们建议你使用官方 [`@ethereum-sourcify/compilers`](https://github.com/argotorg/sourcify/tree/staging/packages/compilers) 软件包.

在出现错误的情况下 `compile` 函数, `lib-sourcify` 期望抛出的错误有公开 `errors` 包含编译输出的属性 `errors` 属性.

### 固态编译器示例

```typescript
import {
  SolidityOutput,
  ISolidityCompiler,
  SolidityJsonInput,
} from '@ethereum-sourcify/lib-sourcify';
import { useSolidityCompiler } from '@ethereum-sourcify/compilers';

class Solc implements ISolidityCompiler {
  constructor(
    private solcRepoPath: string,
    private solJsonRepoPath: string,
  ) {}

  async compile(
    version: string,
    solcJsonInput: SolidityJsonInput,
    forceEmscripten: boolean = false,
  ): Promise<SolidityOutput> {
    return await useSolidityCompiler(
      this.solcRepoPath,
      this.solJsonRepoPath,
      version,
      solcJsonInput,
      forceEmscripten,
    );
  }
}

const solc = new Solc('/path/to/solc/repo', '/path/to/solcjs/repo');
```

### Vyper 编译器示例

```typescript
import { useVyperCompiler } from '@ethereum-sourcify/compilers';

import {
  IVyperCompiler,
  VyperOutput,
  VyperJsonInput,
} from '@ethereum-sourcify/lib-sourcify';

class Vyper implements IVyperCompiler {
  constructor(private vyperRepoPath: string) {}

  async compile(
    version: string,
    vyperJsonInput: VyperJsonInput,
  ): Promise<VyperOutput> {
    return await useVyperCompiler(this.vyperRepoPath, version, vyperJsonInput);
  }
}
const vyper = new Vyper('/path/to/vyper/repo');
```

## 钉死钱

Sourcify Chain是一个处理块链相互作用的类,例如取取字节码和交易数据.

它支持 HTTP 头经过醚认证的 RPC.js `FetchRequest` 对象.

还支持区域方案协调委员会 `debug_traceTransaction` 财务报告和审定财务报表 `trace_call` 能够获取工厂合同创建字节代码的方法.

### 创建“强化事实”

```typescript
import { SourcifyChain } from '@ethereum-sourcify/lib-sourcify';
import { FetchRequest } from 'ethers';

// Create a SourcifyChain for Ethereum Mainnet
const mainnetChain = new SourcifyChain({
  name: 'Ethereum Mainnet',
  chainId: 1,
  rpc: [
    'https://eth.llamarpc.com',
    new FetchRequest({
      url: 'https://authenticated-rpc.com',
      headers: {
        Authorization: 'Bearer ...',
      },
    }),
    'https://eth-mainnet.g.alchemy.com/v2/MY_API_KEY',
  ],
  traceSupportedRPCs: [
    {
      type: 'trace_transaction', // or 'debug_traceTransaction'
      index: 2, // index of the RPC in the rpc array
    },
  ],
  supported: true,
});
```

### 使用经认证的RPC

对于需要认证的RPC,您可以在配置中直接指定标题:

```typescript
import { SourcifyChain } from '@ethereum-sourcify/lib-sourcify';

const authenticatedChain = new SourcifyChain({
  name: 'Protected Network',
  chainId: 1234,
  rpc: [
    {
      type: 'FetchRequest',
      url: 'https://protected-rpc.example.com',
      headers: [
        {
          headerName: 'Authorization',
          headerValue: 'Bearer my-auth-token',
        },
        {
          headerName: 'X-API-Key',
          headerValue: 'my-api-key',
        },
      ],
    },
  ],
  supported: true,
});
```

## 验证

注:Vyper合同不支持通过元数据文件进行验证,因为它们没有将元数据JSON字段纳入其字节代码. 相反,Vyper合同必须直接使用其源文件和编译器设置进行验证.

### 用元数据验证团结合同

v2 介绍 `SolidityMetadataContract` 管理验证工作流程的类 :

```typescript
import { SolidityMetadataContract } from '@ethereum-sourcify/lib-sourcify';

// Create a SolidityMetadataContract with metadata and sources
const metadataContract = new SolidityMetadataContract(metadata, sources);

// Create a compilation object that can be used for verification
const compilation = await metadataContract.createCompilation(solidityCompiler);
```

对于基于文件的校验 :

```typescript
import {
  createMetadataContractsFromFiles,
  PathBuffer,
} from '@ethereum-sourcify/lib-sourcify';

const pathBuffers: PathBuffer[] = [];
pathBuffers.push({
  path: filePath,
  buffer: fs.readFileSync(filePath),
});

// Create SolidityMetadataContract objects from files
const metadataContracts = await createMetadataContractsFromFiles(pathBuffers);

// Create compilation objects
for (const contract of metadataContracts) {
  const compilation = await contract.createCompilation(solidityCompiler);
  // Use compilation for verification
}
```

### 获取缺失的源

每个合同来源都有一个 `content` 字段中包含作为字符串的固态代码,或从(Github, IPFS, Swarm等)获取源的URL。 如果来源缺失, 您可以获取 :

```typescript
// Fetch missing sources
await metadataContract.fetchMissing();
```

将利用配置的森林小组网关获取森林小组资源。 您可以使用 `SolidityMetadataContract.setGlobalIpfsGateway()` global配置一节中所示的方法.

您可以检查合同是否准备与:

```typescript
const isCompilable = metadataContract.isCompilable(); // true or false
```

## 核查

在v2中,核查过程由 `Verification` 类 :

```typescript
import { Verification, SourcifyChain } from '@ethereum-sourcify/lib-sourcify';

// Set up the SourcifyChain
const chain = new SourcifyChain({
  name: 'Ethereum Mainnet',
  chainId: 1,
  rpc: ['https://eth.llamarpc.com'],
  supported: true,
});

// Create a verification instance
const verification = new Verification(
  compilation,
  chain,
  contractAddress,
  creatorTxHash, // optional, for creation bytecode verification
);

// Perform verification
await verification.verify();

// Check verification status
console.log(verification.status.runtimeMatch); // 'perfect', 'partial', or null
```

### 转换

采用 [验证联盟](https://verifieralliance.org/) 用于描述从编译的字节代码到链上字节代码的修改.

例如,当不可变变量设定为 `0x00..00` 在编译后,它们被设定为链字节码中的实际值.

参见 [VerA 文档](https://github.com/verifier-alliance/database-specs/tree/master/json-schemas) 更多信息.

## 处理错误

在核查期间,可能发生各种错误。 在 lib- surcify v2 中,与校验相关的错误被抛出为 `VerificationError` 实例,以扩展 `SourcifyLibError` 课。 这些错误包括一个消息和一个可以用来处理不同错误案件的错误代码.

### 错误代码

见 `VerificationErrorCode` 类型在 [验证类型( T)](https://npmcn.com/package/%40ethereum-sourcify/lib-sourcify/src/Verification/VerificationTypes.ts#L14-L23) 用于完整错误代码列表.

## 日志

`lib-sourcify` 拥有可以在全球配置的基本伐木系统.

您可以使用 `setLibSourcifyLoggerLevel(level)` 函数,其中:

-   `0` 是错误
-   `1` 为警告
-   `2` 属于信息
-   `5` 正在调试
-   `6` 这么傻

您可以使用 `getLibSourcifyLoggerLevel()`。 。 。 .

您可以通过调用来覆盖日志 `setLogger(logger: ILibSourcifyLogger)`数字 :

```javascript
const winston = require('winston');
const myCustomLogger = winston.createLogger({
  // ...
});

setLibSourcifyLogger({
  logLevel: 2, // What levels to log. E.g. Log anything lower than info: error and warning
  setLevel(level: number) {
    this.logLevel = level;
  },
  log(level, msg) {
    if (level <= this.logLevel) {
      switch (level) {
        case 0:
          myCustomLogger.error(msg);
          break;
        case 1:
          myCustomLogger.warn(msg);
          break;
        case 2:
          myCustomLogger.info(msg);
          break;
        case 5:
          myCustomLogger.debug(msg);
          break;
      }
    }
  },
});
```

## EtherscanUtils 以太子化工厂

EtherscanUtils为从Etherscan API进口和处理经核实的合同提供公用事业.

### 从 Etherscan 获取合同数据

```typescript
import { EtherscanUtils } from '@ethereum-sourcify/lib-sourcify';

// Fetch contract source code and metadata from Etherscan
const etherscanResult = await EtherscanUtils.fetchFromEtherscan(
  1, // chainId
  '0x6B175474E89094C44Da98b954EedeAC495271d0F', // contract address
  'YOUR_API_KEY', // API key
);
```

### 根据以太色计算结果创建汇编

```typescript
// Create a compilation object directly from Etherscan data
const compilation = await EtherscanUtils.getCompilationFromEtherscanResult(
  etherscanResult,
  solidityCompiler, // ISolidityCompiler instance
  vyperCompiler, // IVyperCompiler instance (for Vyper contracts)
);

// Use the compilation for verification
const verification = new Verification(compilation, chain, contractAddress);
await verification.verify();
```

## 从v1到v2的迁移指南

Lib-sourcify 第2版带来了图书馆建筑的重大重新设计. 以下是如何从v1迁移到v2:

### 密钥更改

1.  **类结构变化**数字 :
    
    -   `AbstractCheckedContract` 被特定语言的汇编类所取代
    -   `SolidityCheckedContract` 函数现在被拆分 `SolidityMetadataContract` 财务报告和审定财务报表 `SolidityCompilation`
    -   `VyperCheckedContract` 现改为: `VyperCompilation`
    -   新设 `Verification` 类处理核查进程
2.  **工作流程变化**数字 :
    
    -   审定、汇编和核查现在是单独的步骤
    -   对核查进程的更明确的控制

### 移徙实例

#### 从v1:使用固态检查合同

```typescript
// V1 code
const checkedContracts = await checkFilesWithMetadata(solc, pathBuffers);
const solidityCheckedContract = checkedContracts[0];
await solidityCheckedContract.fetchMissing();
const match = await verifyDeployed(
  solidityCheckedContract,
  sourcifyChain,
  contractAddress,
);
```

#### 到 v2: 使用固态元数据合同与验证

```typescript
// V2 code
import {
  createMetadataContractsFromFiles,
  Verification,
} from '@ethereum-sourcify/lib-sourcify';

// Create metadata contracts from files
const metadataContracts = await createMetadataContractsFromFiles(pathBuffers);
const metadataContract = metadataContracts[0];

// Fetch missing sources
await metadataContract.fetchMissing();

// Create compilation
const compilation = await metadataContract.createCompilation(solc);

// Create verification instance
const verification = new Verification(
  compilation,
  sourcifyChain,
  contractAddress,
);

// Perform verification
await verification.verify();

// Check verification status
const status = verification.status;
```

## V1 vs 2 的函数

| v1 函数/ 类 | v2 等价键 |
| --- | --- |
| `SolidityCheckedContract` | `SolidityMetadataContract` + 键 `SolidityCompilation` |
| `VyperCheckedContract` | `VyperCompilation` |
| `checkFilesWithMetadata` | `createMetadataContractsFromFiles` |
| `verifyDeployed` | `Verification.verify()` |
| `fetchMissing` | `metadataContract.fetchMissing()` |
| `isValid` | `metadataContract.isCompilable()` |

## 常见问题

### @ethereum-sourcify/lib-sourcify 是什么？

苏中合同核查方法库,合同验证,类型,界面\.

### 如何安装 @ethereum-sourcify/lib-sourcify？

在项目目录运行 npm install @ethereum-sourcify/lib-sourcify，或使用 pnpm add / yarn add / bun add。

### @ethereum-sourcify/lib-sourcify 支持 TypeScript 吗？

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

### @ethereum-sourcify/lib-sourcify 支持 ESM 还是 CommonJS？

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

### @ethereum-sourcify/lib-sourcify 需要什么版本的 Node\.js？

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

### @ethereum-sourcify/lib-sourcify 可以商用吗？

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

### @ethereum-sourcify/lib-sourcify 的下载量有多少？

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

### @ethereum-sourcify/lib-sourcify 还在维护吗？

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