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

Ephemeral Permission

EphemeralPermission accounts live entirely on the Ephemeral Rollup and are paid for by the delegated PDA — no base-layer permission account to create, delegate, or commit-and-undelegate. Three CPI ops cover the full lifecycle: Create, Update, Close — all PDA-signed by the data account on the ER, via MagicBlock’s Permission Program ACLseoPoyC3cBqoUtkbjZ4aDrkurZW86v19pXz2XQnp1.
Prerequisite — delegate the data PDA. Only the data account is delegated to the TEE validator (on the base layer, via MagicBlock’s Delegation Program DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh). Once delegated, the PDA signs all three permission ops on the ER using its program seeds and pays the ephemeral permission rent — so it must be pre-funded at initialize time. See Quickstart for the end-to-end flow.

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
  • TEE (mainnet-tee.magicblock.app): MTEWGuqxUpYZGFJQcp8tLN7x5v9BSeoFHYWQQ3n3xzo
Devnet
  • Asia (devnet-as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57
  • EU (devnet-eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e
  • US (devnet-us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd
  • TEE (devnet-tee.magicblock.app): MTEWGuqxUpYZGFJQcp8tLN7x5v9BSeoFHYWQQ3n3xzo
Localnet
  • Local ER (localhost:7799): mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev
1

Create Ephemeral Permission

Initialize a new EphemeralPermission account on the ER with initial members and the privacy flag. Idempotent — skip if it already exists.
2

Update Ephemeral Permission

Toggle the privacy flag, or add / remove / reflag members. Updates take effect immediately on the ER.
3

Close Ephemeral Permission

Close the EphemeralPermission account on the ER and refund the rent to the data PDA when the permission is no longer needed.

Ephemeral Permission Operations

Initialize a new EphemeralPermission account on the ER via CreateEphemeralPermissionCpi. Payer = the delegated data PDA, which signs with its program seeds and covers the rent from the lamports pre-funded at initialize time.
use ephemeral_rollups_sdk::access_control::{
    instructions::CreateEphemeralPermissionCpi,
    structs::{EphemeralMembersArgs, Member},
};

// Counter PDA pays for its own permission rent (it carries lamports onto the ER
// after delegation and signs as PDA via seeds).
let signers = [
    COUNTER_SEED,
    ctx.accounts.counter.authority.as_ref(),
    &[ctx.bumps.counter],
];

CreateEphemeralPermissionCpi {
    payer: ctx.accounts.counter.to_account_info(),                  // pays ephemeral rent
    permissioned_account: ctx.accounts.counter.to_account_info(),   // what the permission gates
    permission: ctx.accounts.permission.to_account_info(),
    vault: ctx.accounts.ephemeral_vault.to_account_info(),
    magic_program: ctx.accounts.magic_program.to_account_info(),
    permission_program: ctx.accounts.permission_program.to_account_info(),
    args: EphemeralMembersArgs {
        is_private: false,    // start public — flip via UpdateEphemeralPermission
        members: vec![],
    },
}
.invoke_signed(&[&signers])?;
Use Cases:
  • Bootstrap access control for a newly delegated PDA on the ER
  • Start public (is_private: false, empty members) and tighten later via Update
⬆️ Back to Top
Reference implementations: private-counter (Anchor) and pinocchio-private-counter.

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
  • Default Authority: By default, the owner of the permissioned account is added as permission authority to members of permission account.
  • Empty Member List: If members field is set to empty list, the permissioned account is fully restricted and private. Only the owner of permissioned account can modify the permission.
  • Access Auditing: Use member flags to audit and control access

Access Control

Fine-grained Access Control

On-chain Privacy

Privacy Mechanisms and Concepts

Authorization

Authorization Framework

Compliance Framework

Compliance Standards and Guidelines