Skip to main content

Permission Program

On-chain Permission Management (Coming soon)

Ephemeral Rollups SDK

SDK for Private Ephemeral Rollups

Overview

Private Ephemeral Rollups are Ephemeral Rollups that enable fine-grained permission over permissioned accounts in a Trusted Execution Environment with compliance at its heart. Each permission account maintains a list of members with specific flags that determine what actions they can perform.

Key Concepts

  • Permission Account: A PDA that stores access control rules for a specific account
  • Members: Addresses granted specific permissions via flags
  • Flags: Bitmasks that define what a member can do (authority, view logs, view balances, etc.)
  • Public Permissions: When members are set to None, the permissioned account becomes temporarily visible

Member Flags

Member flags define fine-grained permissions for each member. Flags can be combined using bitwise OR to grant multiple permissions. Flag Descriptions:
  • AUTHORITY: Allows a member to update and delegate permission settings, add/remove other members, and update member flags.
  • TX_LOGS: Allows a member to view transaction execution logs.
  • TX_BALANCES: Allows a member to view account balance changes.
  • TX_MESSAGE: Allows a member to view transaction message data.
  • ACCOUNT_SIGNATURES: Allows a member to view 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

Permission Lifecycle

The typical lifecycle of a permissioned account requires interaction with MagicBlock’s Permission Program ACLseoPoyC3cBqoUtkbjZ4aDrkurZW86v19pXz2XQnp1 and Delegation Program DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh:
1
Initialize a new permission account with initial members and their flags.
2
Delegate the permission to Private Ephemeral Rollup to enable enforcement and real-time access control.

These public validators are supported for development. Make sure to add the specific ER validator in your delegation instruction:

Mainnet
  • Asia (as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57
  • EU (eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e
  • US (us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd
Devnet
  • Asia (devnet-as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57
  • EU (devnet-eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e
  • US (devnet-us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd
  • TEE (tee.magicblock.app): FnE6VJT5QNZdedZPnCoLsARgBwoE6DeJNjBs2H1gySXA
Localnet
  • Local ER (localhost:7799): mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev
3
Add, remove, or modify member permissions as needed. Updates can be made in real-time on Private Ephemeral Rollup.
4
Before making requests, verify TEE RPC integrity and obtain an authorization token. Only members with appropriate flags can access or modify the account state.
5
Sync the final state back to Solana and return the account to Base Layer control.
6
Close the permission account and reclaim its lamports when no longer needed.

Permission Operations

Once you’ve created your program, you can add permission and delegation hooks to control access to your accounts. For example, see Quickstart.Create a new permission account with initial members and their flags via MagicBlock’s 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()])?;
Use Cases:
  • Initialize access control for a new delegated account
  • Set up authority members and their permissions
  • Define who can view transaction details
⬆️ Back to Top

Best Practices

  1. Authority Management: Always assign AUTHORITY_FLAG to at least one trusted member
  2. Least Privilege: Grant only necessary flags to each member
  3. Real-time Updates: Permissions can be updated in real-time on Private Ephemeral Rollup without undelegating, allowing dynamic access control adjustments
  4. Cleanup: Undelegate and close unused permission accounts to free SOL

Security Considerations

  • Signer Validation: Only members with AUTHORITY_FLAG or program with permissioned account can authorize changes
  • Public Accounts: Setting members to None makes the account publicly visible
  • Access Auditing: Use member flags to audit and control access