索拉纳网关

网关协议是一种协议，它允许 Solana 程序限制对有效网关令牌持有者的访问。

• 功能细节
• 集成
• 入门指南
• 技术细节

功能细节

网关令牌是一种链上、不可转让的令牌，dApp 可以发行、冻结或撤销以控制用户访问。

有效网关令牌的存在证明用户的钱包已根据 dApp 的要求进行了验证。

dApp 可以在允许交易通过之前验证钱包的网关令牌状态，从而阻止不符合要求的用户。

网关令牌由守门人发行。守门人可能是一个 dApp、执行 KYC 的组织或从用户那里获取 KYC 信息并代表其发行网关令牌的第三方。

具有类似发行网关令牌规则的守门人集群被定义为守门人网络。守门人网络由公钥标识。此密钥（可能由 DAO 或多重签名拥有）有权向网络添加和删除守门人。

通常，用户的钱包可以与多个网关令牌关联（1:N），但令牌只为单个特定的守门人网络发行（1:1）。

创建门卫网络是一个无需许可的过程，但是，必须由网络管理机构将门卫添加到网络中。

该程序定义了门卫可以在索拉纳区块链上执行的操作，例如颁发和撤销网关令牌，以及由门卫网络管理机构执行的增加/删除门卫的操作。

集成

本节描述了如何将网关协议集成到您的程序中。

如果您想使用网关协议根据网关令牌限制对程序的访问，请按照以下步骤操作。

集成程序选择一个信任的门卫网络，通过将其公钥添加到程序账户中。

然后，该库将验证网关令牌是否由该网络中的门卫颁发且有效。

要将索拉纳网关集成到您的程序中

在Cargo.toml中

solana-gateway = "<LATEST VERSION>"

在指令处理器中（通常是processor.rs）

use solana_gateway::Gateway;
use solana_program::{
    account_info::AccountInfo,
    program_pack::Pack,
    pubkey::Pubkey,
};

fn process() {
    // The owner of the gateway token
    let owner: AccountInfo;
    // The gateway token presented by the owner
    let gateway_token_account_info: AccountInfo;
    // The gatekeeper network key
    let gatekeeper_network: Pubkey;

    let gateway_verification_result:Result<(), GatewayError> =
        Gateway::verify_gateway_token_account_info(
            &gateway_token_account_info, &owner.key, &gatekeeper_network, None
        );
}

高级用法

默认情况下，如果令牌已过期，则verify函数将失败。这是某些门卫网络中的一个重要安全措施，尤其是那些要求持续监控令牌所有者的网络。

在与此不相关的门卫网络中，建议不设置令牌过期。

然而，在某些场景中，过期的令牌可能仍然被认为是有效的。或者，集成者可能希望设置一个容差值。

忽略过期

let gateway_verification_result:Result<(), GatewayError> =
        Gateway::verify_gateway_token_account_info(
            &gateway_token_account_info, &owner.key, &gatekeeper_network, {
                Some(VerificationOptions {
                    check_expiry: false,
                    ..Default::default()
                },
            }
        );

设置容差

let gateway_verification_result:Result<(), GatewayError> =
        Gateway::verify_gateway_token_account_info(
            &gateway_token_account_info, &owner.key, &gatekeeper_network, {
                Some(VerificationOptions {
                    check_expiry: true,
                    expiry_tolerance_seconds: Some(120),    // allow 2 minutes tolerance for token expiry
                },
            }
        );

入门指南

构建程序的前提条件

1. Rust

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. 索拉纳

$ sh -c "$(curl -sSfL https://release.solana.com/v1.16.17/install)"

要构建程序

$ cargo build-spf

要运行测试

# unit tests
$ cargo test
# functional tests
$ cargo test-sbf

要将程序部署到本地环境

$ cargo build-spf
$ solana-test-validator --bpf-program gatem74V238djXdzWnJf94Wo1DcnuGkfijbf3AuBhfs target/deploy/solana_gateway.so

技术细节

说明

程序提供了以下指令

AddGatekeeper

将新的门卫添加到网络中。

此指令所需的账户

1. [writable, signer] funder_account: 交易付款人账户
2. [writeable] gatekeeper_account: 包含门卫详细信息的目标账户
3. [] gatekeeper_authority: 拥有门卫账户的权威机构
4. [signer] gatekeeper_network: 门卫所属的门卫网络
5. [] Rent sysvar
6. [] 系统程序

RemoveGatekeeper

将门卫的资金退还到地址并使它们的地址无效。

此指令所需的账户

1. [writable] funds_to_account: 将租金退回的账户
2. [writable] gatekeeper_account: 要关闭的门卫账户
3. [] gatekeeper_authority: 拥有门卫账户的权威机构
4. [signer] gatekeeper_network: 门卫所属的门卫网络

Issue

颁发新的网关令牌。

此指令所需的账户

1. [writable, signer] funder_account: 交易付款人账户
2. [writable] gateway_token: 网关令牌的目标账户
3. [] owner: 颁发网关令牌的钱包
4. [] gatekeeper_account: 包含颁发网关令牌的门卫详细信息的账户
5. [signer] gatekeeper_authority: 拥有门卫账户的权限
6. [] gatekeeper_network: 门卫所属的门卫网络
7. [] Rent sysvar
8. [] 系统程序

字段

• seed: Option<AddressSeed>: 用于生成网关令牌的可选种子，允许每个钱包有多个网关令牌
• expire_time: Option<UnixTimestamp>: 可选的Unix时间戳，在此时间戳后颁发的令牌不再有效

SetState

更新网关令牌状态（撤销、冻结或解冻）。

门卫可以冻结或解冻他们颁发的任何网关令牌。此外，任何门卫都可以撤销同一门卫网络中的令牌。

此指令所需的账户

1. [writable] gateway_token: 网关令牌的目标账户
2. [signer] gatekeeper_authority: 正在执行更改的门卫权限
3. [] gatekeeper_account: 包含门卫详细信息的账户

字段

• state: GatewayTokenState: 网关令牌的新状态

UpdateExpiry

更新网关令牌的过期时间。

此指令所需的账户

1. [writable] gateway_token: 网关令牌的目标账户
2. [signer] gatekeeper_authority: 正在执行更改的门卫权限
3. [] gatekeeper_account: 包含门卫详细信息的账户

字段

• expire_time: UnixTimestamp: 网关令牌的新过期时间

AddFeatureToNetwork

向门卫网络添加新功能。一个示例功能是 "UserTokenExpiry"（见下文）。

一个功能存在于门卫网络中，是通过存在一个具有已知地址的PDA来指示的，该地址可从门卫网络地址和功能名称中派生。

此指令所需的账户

1. [signer, writable] funder_account: 为此交易提供资金的账户
2. [signer] gatekeeper_network: 接收功能的大门卫网络
3. [writable] feature_account: 新功能账户
4. [] system_program: 系统程序

字段

• feature: NetworkFeature: 要添加的网络功能

RemoveFeatureFromNetwork

从门卫网络中删除功能。

此指令所需的账户

1. [signer, writable] funds_to_account: 接收资金的账户
2. [signer] gatekeeper_network: 接收功能的大门卫网络
3. [writable] feature_account: 新功能账户

字段

• feature: NetworkFeature: 要删除的网络功能

ExpireToken

在具有用户令牌过期功能的大门卫网络中过期网关令牌。此指令由所有者签署，通常作为来自由网关协议控制的其他程序的CPI。

门卫网络必须启用用户令牌过期功能，这可以通过存在一个具有已知地址的PDA来指示，该地址可从门卫网络地址和功能名称中派生。

此指令所需的账户

1. [writable] gateway_token: 要过期的令牌
2. [signer] owner: 网关令牌所属的钱包
3. [] network_expire_feature: 门卫网络的用户令牌过期功能账户

字段

• padding: Option<AddressSeed>: 与向后兼容性相关的填充
• gatekeeper_network: Pubkey: 门卫网络

BurnToken

从系统中移除网关令牌，关闭账户。与撤销网关令牌不同，这不会在链上留下开放的账户，并且可以通过重新发行令牌来撤销。

此指令所需的账户

1. [writable] gateway_token: 网关令牌的账户
2. [signer] gatekeeper_authority: 燃烧令牌的门卫权限
3. [] gatekeeper_account: 将门卫权限与门卫网络链接的门卫账户
4. [writeable] recipient: 网关令牌账户中的lamports的接收者

账户结构

网关令牌

定义网关令牌结构。

• version: u8: 用于向后兼容性的版本字段 - 当前为0。
• parent_gateway_token: Option<Pubkey>: 如果令牌是会话令牌，则将其设置为用于生成它的父令牌。注意：已弃用 - 保留以保持向后兼容性，但不再使用。
• owner_wallet: Pubkey: 被分配此令牌的钱包的公钥。
• owner_identity: Option<Pubkey>: 被分配令牌的身份的DID（必须在Solana上）。注意：已弃用 - 保留以保持向后兼容性，但不再使用。
• gatekeeper_network: Pubkey: 发行令牌的网关网络。
• issuing_gatekeeper: Pubkey: 发行令牌的具体门卫。
• state: GatewayTokenState: 当前令牌状态。
• expire_time: Option<UnixTimestamp>: 令牌的过期时间（Unix时间戳）（仅限可过期令牌）。

功能

功能是门卫网络的可启用或禁用属性。

它们由一个PDA表示，其地址可从门卫网络地址和功能名称推导出来。

目前只支持一个功能：UserTokenExpiry。

UserTokenExpiry功能允许用户为其自己的网关令牌设置过期时间。

此功能的用例是检查然后过期网关令牌的智能合约。

这允许使用“一次性”网关令牌，例如用于令牌销售或空投，使用后需要重新激活。

注意，所有网关令牌都可能有门卫设置的过期时间，无论网络是否支持UserTokenExpiry。

网关令牌状态

令牌可以处于以下状态

• 活动
• 已撤销
• 冻结

只有处于“活动”状态的令牌才被程序接受。

处于“已撤销”状态的代币是无效的，程序应采取措施删除任何使用已撤销代币发行的开放头寸、订单等（有关详细信息，请参见下文）。

已撤销的代币无法重新激活，必须重新发行。

被冻结的代币处于“暂停”状态，新的交易不应接受它们。它们可能因多种原因被冻结，例如，如果用户在受限管辖区尝试使用代币，守门人可能会暂时冻结该代币。冻结/解冻代币可以由发行守门人解冻。

尽管在链上没有表示为状态，代币也可能有“已过期”，在这种情况下，它们被视为冻结。