跳转到主要内容

Permission Program

链上权限管理(即将推出)

Ephemeral Rollups SDK

用于 Private Ephemeral Rollups 的 SDK

概述

Private Ephemeral Rollups 是 Ephemeral Rollups 的一种形式,它在以合规为核心的 Trusted Execution Environment 中,为受权限控制的账户提供细粒度权限管理。每个权限账户都会维护一份成员列表,并通过特定标志来决定这些成员可以执行哪些操作。

核心概念

  • Permission Account:用于存储特定账户访问控制规则的 PDA
  • Members:通过标志授予特定权限的地址
  • Flags:用于定义成员可执行操作的位掩码(authority、查看日志、查看余额等)
  • Public Permissions:当成员被设置为 None 时,受权限控制的账户会暂时变为可见

成员标志

成员标志为每位成员定义细粒度权限。你可以通过按位 OR 组合多个标志,以授予多个权限。 标志说明:
  • AUTHORITY:允许成员更新和委托权限设置、添加或移除其他成员,以及更新成员标志。
  • TX_LOGS:允许成员查看交易执行日志。
  • TX_BALANCES:允许成员查看账户余额变更。
  • TX_MESSAGE:允许成员查看交易消息数据。
  • ACCOUNT_SIGNATURES:允许成员查看账户签名
use ephemeral_rollups_sdk::access_control::structs::{
    Member,
    AUTHORITY_FLAG,
    TX_LOGS_FLAG,
    TX_BALANCES_FLAG,
    TX_MESSAGE_FLAG,
    ACCOUNT_SIGNATURES_FLAG,
};

// Set flags by combining them with bitwise OR
let flags = AUTHORITY_FLAG | TX_LOGS_FLAG;

// Create a member with combined flags
let mut member = Member {
    flags,
    pubkey: user_pubkey,
};

// Check if member has a specific flag using bitwise AND
let is_authority = (member.flags & AUTHORITY_FLAG) != 0;
let can_see_logs = (member.flags & TX_LOGS_FLAG) != 0;

// Use helper methods to set/remove flags
member.set_flags(TX_BALANCES_FLAG); // Add a flag
member.remove_flags(TX_LOGS_FLAG);  // Remove a flag

权限生命周期

一个受权限控制账户的典型生命周期需要与 MagicBlock 的 Permission Program ACLseoPoyC3cBqoUtkbjZ4aDrkurZW86v19pXz2XQnp1 以及 Delegation Program DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh 交互:
1

创建权限

使用初始成员及其标志初始化一个新的权限账户。
2

委托权限

将权限委托给 Private Ephemeral Rollup,以启用强制执行和实时访问控制。

这些公共验证器可用于开发环境。请确保在你的委托指令中添加对应的 ER 验证器:

主网
  • 亚洲 (as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57
  • 欧盟 (eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e
  • 美国 (us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd
  • TEE (mainnet-tee.magicblock.app): MTEWGuqxUpYZGFJQcp8tLN7x5v9BSeoFHYWQQ3n3xzo
开发网
  • 亚洲 (devnet-as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57
  • 欧盟 (devnet-eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e
  • 美国 (devnet-us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd
  • TEE (devnet-tee.magicblock.app): FnE6VJT5QNZdedZPnCoLsARgBwoE6DeJNjBs2H1gySXA
本地网络
  • 本地 ER (localhost:7799): mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev
3

更新权限

根据需要添加、移除或修改成员权限。更新可以在 Private Ephemeral Rollup 上实时完成。
4

发起请求

在发起请求之前,先验证 TEE RPC 的完整性并获取授权令牌。只有拥有相应标志的成员才能访问或修改账户状态。
5

提交并取消委托

将最终状态同步回 Solana,并把账户归还给 Base Layer 控制。
6

关闭权限

当不再需要时关闭权限账户,并回收其中的 lamports。

权限操作

创建好程序后,你可以添加权限和委托钩子来控制对账户的访问。例如可参考快速开始通过 MagicBlock 的 Permission Program ACLseoPoyC3cBqoUtkbjZ4aDrkurZW86v19pXz2XQnp1 创建一个带有初始成员及其标志的新权限账户。
use ephemeral_rollups_sdk::access_control::{
    instructions::CreatePermissionCpiBuilder,
    structs::{
        Member,
        MembersArgs,
        AUTHORITY_FLAG,        // Member can directly modify the permission
        TX_LOGS_FLAG,          // Member can view transaction logs
        TX_BALANCES_FLAG       // Member can view account balances
    }
};

let members = Some(vec![
    Member {
        // AUTHORITY_FLAG allows this member to modify permission settings
        // TX_LOGS_FLAG allows viewing transaction logs
        flags: AUTHORITY_FLAG | TX_LOGS_FLAG,
        pubkey: *payer.key,
    },
]);

// Note: Either the authority or permissioned_account can sign the transaction
// The signer depends on who has AUTHORITY_FLAG in the members list
CreatePermissionCpiBuilder::new(&permission_program)
    .permissioned_account(&permissioned_account)
    .permission(&permission)
    .payer(&payer)
    .system_program(&system_program)
    .args(MembersArgs { members })
    .invoke_signed(&[seed_refs.as_slice()])?;
使用场景:
  • 为新的委托账户初始化访问控制
  • 设置 authority 成员及其权限
  • 定义谁可以查看交易详情
⬆️ 返回顶部

最佳实践

  1. Authority 管理:始终至少为一位可信成员分配 AUTHORITY_FLAG
  2. 最小权限原则:仅向每位成员授予必要的标志
  3. 实时更新:权限可以在不取消委托的情况下于 Private Ephemeral Rollup 上实时更新,从而实现动态访问控制调整
  4. 清理:取消委托并关闭未使用的权限账户,以释放 SOL

安全注意事项

  • 签名者验证:只有拥有 AUTHORITY_FLAG 的成员或带有受权限控制账户的程序才能授权变更
  • 公开账户:将成员设置为 None 会使账户对外公开可见
  • 默认 Authority:默认情况下,受权限控制账户的所有者会被添加为权限账户成员中的 permission authority
  • 空成员列表:如果 members 字段被设置为空列表,则受权限控制账户将完全受限且保持私密。只有该账户所有者才能修改权限
  • 访问审计:使用成员标志来审计和控制访问

访问控制

细粒度访问控制

链上隐私

隐私机制与核心概念

授权

授权框架

合规框架

合规标准与指南