模式 | Solana

模式定义了 Solana 证明系统中凭证的结构和验证规则。模式作为模板,指定凭证应包含哪些字段以及如何格式化这些字段。每个模式都与一个凭证类型关联,并可以进行版本控制以支持数据结构的演进。

结构

Schema 结构体表示 Solana 证明系统中的一个模式。每个模式都为可在其下创建的凭证定义了一个模板。

类型定义

Schema

export type Schema = {
  discriminator: number; // Internal discriminator
  credential: Address; // Associated credential address
  name: ReadonlyUint8Array; // Schema name
  description: ReadonlyUint8Array; // Schema description
  layout: ReadonlyUint8Array; // Schema layout definition
  fieldNames: ReadonlyUint8Array; // Names of fields in the schema
  isPaused: boolean; // Pause status
  version: number; // Schema version
};

方法

获取模式

方法	描述	参数	返回值
`fetchSchema`	通过地址获取单个模式	`rpc`: RPC 上下文, `address`: 模式地址, `config?`: 获取配置	`Promise<Account<Schema>>`
`fetchMaybeSchema`	安全获取模式,如果未找到则返回 null	`rpc`: RPC 上下文, `address`: 模式地址, `config?`: 获取配置	`Promise<MaybeAccount<Schema>>`
`fetchAllSchema`	通过地址获取多个模式	`rpc`: RPC 上下文, `addresses`: 模式地址数组, `config?`: 获取配置	`Promise<Account<Schema>[]>`
`fetchAllMaybeSchema`	安全获取多个模式,跳过未找到的	`rpc`: RPC 上下文, `addresses`: 模式地址数组, `config?`: 获取配置	`Promise<MaybeAccount<Schema>[]>`

序列化

方法	描述	参数	返回值
`getSchemaEncoder`	获取模式数据的编码器	无	`Encoder<SchemaArgs>`
`getSchemaDecoder`	获取模式数据的解码器	无	`Decoder<Schema>`
`getSchemaCodec`	获取模式数据的编解码器	无	`Codec<SchemaArgs, Schema>`

使用示例

获取单个模式

const schema = await fetchSchema(rpc, schemaAddress);
console.log("Schema name:", schema.name);

获取多个模式

const schemas = await fetchAllSchema(rpc, [schema1Address, schema2Address]);
schemas.forEach((schema) => console.log("Schema:", schema.name));

安全获取

const schema = await fetchMaybeSchema(rpc, schemaAddress);
if (schema) {
  console.log("Schema found:", schema.name);
} else {
  console.log("Schema not found");
}

模式布局数据类型

layout 字段使用数值来指定模式中每个字段的数据类型：

值	数据类型	描述
0	U8	无符号 8 位整数
1	U16	无符号 16 位整数
2	U32	无符号 32 位整数
3	U64	无符号 64 位整数
4	U128	无符号 128 位整数
5	I8	有符号 8 位整数
6	I16	有符号 16 位整数
7	I32	有符号 32 位整数
8	I64	有符号 64 位整数
9	I128	有符号 128 位整数
10	Bool	布尔值
11	Char	单个字符
12	String	可变长度字符串
13	VecU8	无符号 8 位整数向量
14	VecU16	无符号 16 位整数向量
15	VecU32	无符号 32 位整数向量
16	VecU64	无符号 64 位整数向量
17	VecU128	无符号 128 位整数向量
18	VecI8	有符号 8 位整数向量
19	VecI16	有符号 16 位整数向量
20	VecI32	有符号 32 位整数向量
21	VecI64	有符号 64 位整数向量
22	VecI128	有符号 128 位整数向量
23	VecBool	布尔值向量
24	VecChar	字符向量
25	VecString	字符串向量

使用示例

例如，[12, 0, 12] 的布局将定义三个字段：一个字符串，后跟一个 U8 整数，再后跟另一个字符串。fieldNames 数组提供了与每个布局值位置对应的人类可读名称，因此使用字段名称 ["name", "age", "country"] 时，第一个字符串字段将被命名为"name"，U8 字段将是"age"，第二个字符串字段将是"country"。

以下是创建模式时如何使用这些内容的示例：

const createSchemaInstruction = getCreateSchemaInstruction({
  authority,
  payer,
  credential: credentialPda,
  schema: schemaPda,
  name: "Test Schema",
  description: "Just an example",
  fieldNames: ["name", "age", "country"],
  layout: Buffer.from([12, 0, 12])
});

重要说明

discriminator 字段供内部使用，不应修改
credential 字段将模式与其关联的凭证类型链接
isPaused 可用于临时禁用模式使用
version 字段允许模式演进，同时保持向后兼容性
layout 和 fieldNames 定义了使用此模式的凭证结构
所有字节数组字段（name、description、layout、fieldNames）应根据您的应用程序需求进行正确编码/解码

Table of Contents