From 69763668d3da81582dbbb08f9bc554e74ced6ff9 Mon Sep 17 00:00:00 2001 From: jonasXchen Date: Tue, 30 Sep 2025 10:32:23 +0800 Subject: [PATCH 1/9] feat: improved discoverability and usability of products, demos, starter kits and RFP --- docs.json | 148 ++-- .../api-and-sdk/overview.mdx | 7 + .../how-to-guide/anchor.mdx | 275 ++++++++ .../how-to-guide/local-development.mdx | 191 ++++++ .../how-to-guide/quickstart.mdx | 287 ++++++++ .../how-to-guide/rust.mdx | 639 ++++++++++++++++++ .../introduction/ephemeral-rollup.mdx | 49 ++ .../introduction/magic-router.mdx | 84 +++ .../introduction/transactions.mdx | 96 +++ .../introduction/why.mdx | 93 +++ pages/overview.mdx | 35 + .../additional-information/pricing.mdx | 47 ++ .../security-and-audits.mdx | 24 + .../additional-information/server-status.mdx | 7 + .../additional-information/whitepaper.mdx | 19 + .../guides-and-starter-kits/overview.mdx | 53 ++ .../products/ephemeral-rollups-er.mdx | 7 + .../trusted-execution-environments-tee.mdx | 7 + .../verifiable-randomness-functions-vrf.mdx | 7 + pages/tools/introduction.mdx | 25 +- pages/tools/tee/program-implementation.mdx | 5 +- .../api-and-sdk/overview.mdx | 7 + .../how-to-guide/client-implementation.mdx | 65 ++ .../how-to-guide/program-implementation.mdx | 84 +++ .../introduction/authorization.mdx | 21 + .../introduction/onchain-privacy.mdx | 63 ++ .../api-and-sdk/overview.mdx | 7 + .../how-to-guide/overview.mdx | 7 + .../introduction/best-practices.mdx | 25 + .../introduction/faq.mdx | 20 + .../introduction/security.mdx | 19 + .../introduction/technical-details.mdx | 25 + .../what-is-verifiable-randomness.mdx | 24 + .../introduction/why.mdx | 7 + snippets/construction.mdx | 5 + snippets/demo-cards.mdx | 59 ++ snippets/product-cards.mdx | 26 + snippets/tee-cards.mdx | 26 + 38 files changed, 2530 insertions(+), 65 deletions(-) create mode 100644 pages/ephemeral-rollups-ers/api-and-sdk/overview.mdx create mode 100644 pages/ephemeral-rollups-ers/how-to-guide/anchor.mdx create mode 100644 pages/ephemeral-rollups-ers/how-to-guide/local-development.mdx create mode 100644 pages/ephemeral-rollups-ers/how-to-guide/quickstart.mdx create mode 100644 pages/ephemeral-rollups-ers/how-to-guide/rust.mdx create mode 100644 pages/ephemeral-rollups-ers/introduction/ephemeral-rollup.mdx create mode 100644 pages/ephemeral-rollups-ers/introduction/magic-router.mdx create mode 100644 pages/ephemeral-rollups-ers/introduction/transactions.mdx create mode 100644 pages/ephemeral-rollups-ers/introduction/why.mdx create mode 100644 pages/overview.mdx create mode 100644 pages/overview/additional-information/pricing.mdx create mode 100644 pages/overview/additional-information/security-and-audits.mdx create mode 100644 pages/overview/additional-information/server-status.mdx create mode 100644 pages/overview/additional-information/whitepaper.mdx create mode 100644 pages/overview/guides-and-starter-kits/overview.mdx create mode 100644 pages/overview/products/ephemeral-rollups-er.mdx create mode 100644 pages/overview/products/trusted-execution-environments-tee.mdx create mode 100644 pages/overview/products/verifiable-randomness-functions-vrf.mdx create mode 100644 pages/trusted-execution-environments-tees/api-and-sdk/overview.mdx create mode 100644 pages/trusted-execution-environments-tees/how-to-guide/client-implementation.mdx create mode 100644 pages/trusted-execution-environments-tees/how-to-guide/program-implementation.mdx create mode 100644 pages/trusted-execution-environments-tees/introduction/authorization.mdx create mode 100644 pages/trusted-execution-environments-tees/introduction/onchain-privacy.mdx create mode 100644 pages/verifiable-randomness-functions-vrfs/api-and-sdk/overview.mdx create mode 100644 pages/verifiable-randomness-functions-vrfs/how-to-guide/overview.mdx create mode 100644 pages/verifiable-randomness-functions-vrfs/introduction/best-practices.mdx create mode 100644 pages/verifiable-randomness-functions-vrfs/introduction/faq.mdx create mode 100644 pages/verifiable-randomness-functions-vrfs/introduction/security.mdx create mode 100644 pages/verifiable-randomness-functions-vrfs/introduction/technical-details.mdx create mode 100644 pages/verifiable-randomness-functions-vrfs/introduction/what-is-verifiable-randomness.mdx create mode 100644 pages/verifiable-randomness-functions-vrfs/introduction/why.mdx create mode 100644 snippets/construction.mdx create mode 100644 snippets/demo-cards.mdx create mode 100644 snippets/product-cards.mdx create mode 100644 snippets/tee-cards.mdx diff --git a/docs.json b/docs.json index aa1ee85..059ff3d 100644 --- a/docs.json +++ b/docs.json @@ -9,43 +9,131 @@ }, "favicon": "/logo/favicon.png", "navigation": { + "tabs": [ { - "tab": "MagicBlock Engine", + "tab": "Overview", "groups": [ { - "group": "MagicBlock Engine", + "group": "Products", "pages": [ - "pages/get-started/introduction/why-magicblock", - "pages/get-started/introduction/ephemeral-rollup", - "pages/get-started/introduction/pricing" + "pages/overview" ] }, { - "group": "How to Integrate Your Program", + "group": "Guides & Starter Kits", "pages": [ - "pages/get-started/how-integrate-your-program/quickstart", - "pages/get-started/how-integrate-your-program/magic-router", - "pages/get-started/how-integrate-your-program/local-setup", - "pages/get-started/how-integrate-your-program/transactions", - "pages/get-started/how-integrate-your-program/anchor", - "pages/get-started/how-integrate-your-program/rust" + "pages/overview/guides-and-starter-kits/overview" ] }, { - "group": "Use Cases", + "group": "Additional Information", "pages": [ - "pages/get-started/use-cases/introduction", - "pages/get-started/use-cases/finance", - "pages/get-started/use-cases/games", - "pages/get-started/use-cases/ai", - "pages/get-started/use-cases/payments", - "pages/get-started/use-cases/depin", - "pages/get-started/use-cases/privacy" + "pages/overview/additional-information/whitepaper", + "pages/overview/additional-information/security-and-audits", + "pages/overview/additional-information/pricing", + "pages/overview/additional-information/server-status" ] } ] }, + { + "tab": "Ephemeral Rollups (ER)", + "groups": [ + { + "group": "Introduction", + "pages": [ + "pages/ephemeral-rollups-ers/introduction/why", + { + "group": "How it Works", + "pages": [ + "pages/ephemeral-rollups-ers/introduction/ephemeral-rollup", + "pages/ephemeral-rollups-ers/introduction/magic-router" + ] + } + + ] + }, + { + "group": "How-to-Guide", + "pages": [ + "pages/ephemeral-rollups-ers/how-to-guide/quickstart", + "pages/ephemeral-rollups-ers/how-to-guide/local-development", + "pages/ephemeral-rollups-ers/how-to-guide/rust", + "pages/ephemeral-rollups-ers/how-to-guide/anchor" + ] + }, + { + "group": "API & SDK", + "pages": [ + "pages/ephemeral-rollups-ers/api-and-sdk/overview" + ] + } + ] + }, + { + "tab": "Trusted Execution Environment (TEE)", + "groups": [ + { + "group": "Introduction", + "pages": [ + "pages/trusted-execution-environments-tees/introduction/onchain-privacy", + "pages/trusted-execution-environments-tees/introduction/authorization" + ] + }, + { + "group": "How-to-Guide", + "pages": [ + "pages/trusted-execution-environments-tees/how-to-guide/program-implementation", + "pages/trusted-execution-environments-tees/how-to-guide/client-implementation" + ] + }, + { + "group": "API & SDK", + "pages": [ + "pages/trusted-execution-environments-tees/api-and-sdk/overview" + ] + } + ] + }, + { + "tab": "Verifiable Randomness Function (VRF)", + "groups": [ + { + "group": "Introduction", + "pages": [ + "pages/verifiable-randomness-functions-vrfs/introduction/what-is-verifiable-randomness", + "pages/verifiable-randomness-functions-vrfs/introduction/technical-details", + "pages/verifiable-randomness-functions-vrfs/introduction/security", + "pages/verifiable-randomness-functions-vrfs/introduction/best-practices", + "pages/verifiable-randomness-functions-vrfs/introduction/faq" + ] + },{ + "group": "How-to-Guide", + "pages": [ + "pages/verifiable-randomness-functions-vrfs/how-to-guide/overview" + ] + }, + { + "group": "API & SDK", + "pages": [ + "pages/verifiable-randomness-functions-vrfs/api-and-sdk/overview" + ] + } + ] + }, + { + "tab": "Guides & Starter Kits", + "groups": [ + { + "group": "Introduction", + "pages": [ + "pages/overview/guides-and-starter-kits/overview" + ] + } + ] + }, + { "tab": "Tools", "groups": [ @@ -145,35 +233,17 @@ } ] }, - { - "group": "Randomness", - "pages": [ - "pages/tools/randomness/what-is-verifiable-randomness", - "pages/tools/randomness/technical-details", - "pages/tools/randomness/security", - "pages/tools/randomness/best-practices", - "pages/tools/randomness/faq" - ] - }, { "group": "Oracles", "pages": [ "pages/tools/oracle/introduction", "pages/tools/oracle/implementation" ] - }, - { - "group": "TEE", - "pages": [ - "pages/tools/tee/introduction", - "pages/tools/tee/program-implementation", - "pages/tools/tee/client-implementation", - "pages/tools/tee/authorization" - ] } ] } ], + "global": { "anchors": [ { diff --git a/pages/ephemeral-rollups-ers/api-and-sdk/overview.mdx b/pages/ephemeral-rollups-ers/api-and-sdk/overview.mdx new file mode 100644 index 0000000..5345aa6 --- /dev/null +++ b/pages/ephemeral-rollups-ers/api-and-sdk/overview.mdx @@ -0,0 +1,7 @@ +--- +title: Overview +--- + +import Construction from "/snippets/construction.mdx"; + + diff --git a/pages/ephemeral-rollups-ers/how-to-guide/anchor.mdx b/pages/ephemeral-rollups-ers/how-to-guide/anchor.mdx new file mode 100644 index 0000000..1d5beab --- /dev/null +++ b/pages/ephemeral-rollups-ers/how-to-guide/anchor.mdx @@ -0,0 +1,275 @@ +--- +title: "Anchor Example" +description: "Learn how to write a simple Anchor program that increments a counter on Solana" +--- + +import Endpoints from "/snippets/endpoints.mdx"; + +
+ + + + Iframes only work with some wallets (e.g. Backpack). Alternatively, try the + deployed demo here: https://main--ephemeral-counter.netlify.app/ + + +### Ephemeral Endpoint Configuration + +To interact with the Ephemeral Rollup session, you need to configure the appropriate endpoint: + +- For devnet, use the following ephemeral endpoint: + + https://devnet.magicblock.app + +- For mainnet, please reach out to the MagicBlock team to receive the appropriate endpoint. +- For localhost, download, install, and run the ephemeral validator locally with the appropriate environment variables. + +Make sure to update your client configuration to use the correct endpoint based on your development or production environment. + + + + + + + diff --git a/pages/ephemeral-rollups-ers/how-to-guide/local-development.mdx b/pages/ephemeral-rollups-ers/how-to-guide/local-development.mdx new file mode 100644 index 0000000..758b563 --- /dev/null +++ b/pages/ephemeral-rollups-ers/how-to-guide/local-development.mdx @@ -0,0 +1,191 @@ +--- +title: "Local Development" +description: "Run and test your Native Rust or Anchor programs with full customization on your local host and Ephemeral Rollups minimizing network latency and rate limit risk." +--- + +import Validators from "/snippets/validators.mdx"; + +--- + +### ⚠️ Important: Upgrade your program with local validator identity + +> When using a local ER validator, you need to connect it to your preferred base layer (e.g., `mainnet-beta`, `devnet`, or `localhost`) where the accounts are delegated. To delegate your PDA to a `specific ER validator identity`, you must update the `delegation config` in your program. This ensures that accounts can be properly committed and undelegated on the base layer. + + + +--- + +### Deploy and test on base layer via correct validator identity + + + + + + 1. Install `solana-test-validator`: + ```bash + sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)" + ``` + + 2. Run `solana-test-validator` with cloned delegation program and accounts from Devnet: + ```bash + solana-test-validator \ + --ledger ./my-ledger-1 \ + --reset \ + --clone mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev \ + --clone EpJnX7ueXk7fKojBymqmVuCuwyhDQsYcLVL1XMsBbvDX \ + --clone 7JrkjmZPprHwtuvtuGTXp9hwfGYFAQLnLeFM52kqAgXg \ + --clone noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV \ + --clone-upgradeable-program DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh \ + --url https://api.devnet.solana.com + ``` + + 3. Upgrade and deploy your program to localhost: + + + ```bash + cargo build-sbf + solana config set --url localhost + solana program deploy YOUR_PROGRAM_PATH + ``` + + + ```bash + anchor build && anchor deploy \ + --provider.cluster localnet + ``` + + + + + + 1. Install the latest MagicBlock Ephemeral Validator: + ```bash + npm install -g @magicblock-labs/ephemeral-validator@latest + ``` + + 2. Run the local ephemeral validator pointing to localhost: + ```bash + RUST_LOG=info ephemeral-validator \ + --accounts-lifecycle ephemeral \ + --remote-cluster development \ + --remote-url http://127.0.0.1:8899 \ + --remote-ws-url ws://127.0.0.1:8900 \ + --rpc-port 7799 + ``` + + + + Run your tests against the local ephemeral validator: + + + + ```bash + EPHEMERAL_PROVIDER_ENDPOINT=http://localhost:7799 \ + EPHEMERAL_WS_ENDPOINT=ws://localhost:7800 \ + PROVIDER_ENDPOINT=http://localhost:8899 \ + WS_ENDPOINT=http://localhost:8900 \ + yarn test + ``` + + + ```bash + EPHEMERAL_PROVIDER_ENDPOINT="http://localhost:7799" \ + EPHEMERAL_WS_ENDPOINT="ws://localhost:7800" \ + anchor test \ + --provider.cluster localnet \ + --skip-local-validator \ + --skip-build \ + --skip-deploy + ``` + + + + + + + + + + Upgrade your program with MagicBlock delegation and deploy it to Devnet: + + + + ```bash + cargo build-sbf + solana config set --url devnet + solana program deploy YOUR_PROGRAM_PATH + ``` + + + ```bash + anchor build && anchor deploy \ + --provider.cluster devnet + ``` + + + + + + + 1. Install the latest MagicBlock Ephemeral Validator: + ```bash + npm install -g @magicblock-labs/ephemeral-validator@latest + ``` + + 2. Run the local ephemeral validator pointing to Devnet: + ```bash + RUST_LOG=info ephemeral-validator \ + --accounts-lifecycle ephemeral \ + --remote-url "https://rpc.magicblock.app/devnet" \ + --rpc-port 7799 + ``` + + + + Run your tests against the local ephemeral validator: + + + ```bash + EPHEMERAL_PROVIDER_ENDPOINT=http://localhost:7799 \ + EPHEMERAL_WS_ENDPOINT=ws://localhost:7800 \ + yarn test + ``` + + + ```bash + EPHEMERAL_PROVIDER_ENDPOINT="http://localhost:7799" \ + EPHEMERAL_WS_ENDPOINT="ws://localhost:7800" \ + anchor test \ + --provider.cluster devnet \ + --skip-local-validator \ + --skip-build \ + --skip-deploy + ``` + + + + + + + + +Explore delegation and test scripts for both Anchor and Native Rust: + + + + Integrate with an Anchor program + + + Integrate with a Native Rust program + + diff --git a/pages/ephemeral-rollups-ers/how-to-guide/quickstart.mdx b/pages/ephemeral-rollups-ers/how-to-guide/quickstart.mdx new file mode 100644 index 0000000..7207eec --- /dev/null +++ b/pages/ephemeral-rollups-ers/how-to-guide/quickstart.mdx @@ -0,0 +1,287 @@ +--- +title: "Quickstart" +description: "Any Solana program can be upgraded with Ephemeral Rollups by adding delegation capabilities." +--- + +import Endpoints from "/snippets/endpoints.mdx"; +import Validators from "/snippets/validators.mdx"; + +--- + +## Lifecycle of the Integration + +The lifecycle of integrating Ephemeral Rollups in your program is as follows: + + + Write your program}> + Write your Solana program as you normally would, using Anchor, native Rust, + Bolt, C, or even assembly. + + + Add delegation and undelegation hooks + + } + > + Accounts that are delegated can be used as writable in an Ephemeral Rollup + session. + + + Deploy your program on Solana + + } + > + Deploy your program directly on Solana. + + + Ready to execute transactions for delegation and real-time speed + + } + > + Execute your transactions without modifications on-chain and off-chain that + also comply with the SVM RPC specification. + + + +--- + +## Step 1: Write your program + +A simple counter program have the following instructions `initialize` and `increment`: + +```rust +#[program] +pub mod anchor_counter { + use super::*; + + /// Initialize the counter. + pub fn initialize(ctx: Context) -> Result<()> { + let counter = &mut ctx.accounts.counter; + counter.count = 0; + Ok(()) + } + + /// Increment the counter. + pub fn increment(ctx: Context) -> Result<()> { + let counter = &mut ctx.accounts.counter; + counter.count += 1; + Ok(()) + } + + // ... Additional instructions will be added here +} + +/// Context for initializing counter +#[derive(Accounts)] +pub struct Initialize<'info> { + #[account(init_if_needed, payer = user, space = 8 + 8, seeds = [TEST_PDA_SEED], bump)] + pub counter: Account<'info, Counter>, + #[account(mut)] + pub user: Signer<'info>, + pub system_program: Program<'info, System>, +} + + +/// Context for incrementing counter +#[derive(Accounts)] +pub struct Increment<'info> { + #[account(mut, seeds = [TEST_PDA_SEED], bump)] + pub counter: Account<'info, Counter>, +} + +/// Counter struct +#[account] +pub struct Counter { + pub count: u64, +} +``` + +Find the full basic counter example for Rust Native and Anchor framework implementation: + + + + Integrate with an Anchor program + + + Integrate with an Native Rust program + + + + +--- + +## Step 2: Add delegation and undelegation hooks + +> `Delegation` is the process of transferring ownership of one or more of your program's `PDAs` to the delegation program. Ephemeral Validators will then be able to use the `PDAs` to perform transactions in the SVM runtime. + +> `Undelegation` is the process of transferring ownership of the `PDAs` back to your program. On undelegation, the state is committed and it trigger the finalization process. Once state it validated, the `PDAs` are unlocked and can be used as normal on mainnet + +**Anchor framework example:** + +1. Add `ephemeral-rollups-sdk` with Anchor features to your program + +```bash +cargo add ephemeral-rollups-sdk --features anchor +``` + +Import `delegate`, `commit`, `ephemeral`, `DelegateConfig`, `commit_accounts` and `commit_and_undelegate_accounts`: + +```rust +use ephemeral_rollups_sdk::anchor::{ + commit, + delegate, + ephemeral +}; +use ephemeral_rollups_sdk::cpi::DelegateConfig; +use ephemeral_rollups_sdk::ephem::{ + commit_accounts, + commit_and_undelegate_accounts + }; +``` + +2. Add `delegate` macro and instruction, `ephemeral` macro, and `undelegate` instruction to your program. Specify your preferred delegation config such as auto commits and specific ER validator: + + + +```rust +#[ephemeral] +#[program] +pub mod anchor_counter { + use super::*; + + // ... Initialize and Incroment instructions. + + /// Delegate the account to the delegation program + /// IMPORTANT: Set specific validator based on ER + pub fn delegate(ctx: Context) -> Result<()> { + ctx.accounts.delegate_pda( + &ctx.accounts.payer, + &[TEST_PDA_SEED], + DelegateConfig { + commit_frequency_ms: 30_000, + validator: Some(pubkey!("MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57")), + }, + )?; + Ok(()) + } + + /// Undelegate the account from the delegation program + pub fn undelegate(ctx: Context) -> Result<()> { + commit_and_undelegate_accounts( + &ctx.accounts.payer, + vec![&ctx.accounts.counter.to_account_info()], + &ctx.accounts.magic_context, + &ctx.accounts.magic_program, + )?; + Ok(()) + } +} + +/// Add delegate function to the context +#[delegate] +#[derive(Accounts)] +pub struct DelegateInput<'info> { + pub payer: Signer<'info>, + /// CHECK The pda to delegate + #[account(mut, del)] + pub pda: AccountInfo<'info>, +} + +// ... Other context and account struct. +``` + +--- + +## Step 3: Deploy your program on Solana + +Now you're program is upgraded and ready! Build and deploy to the desired cluster: + +```rust +anchor build && anchor deploy +``` + +--- + +## Step 4: Ready to execute transactions for delegation and real-time speed + +Use Anchor IDL file to build and send transactions: + +```typescript Frontend +// Set Anchor providers +const provider = anchor.AnchorProvider.env(); +anchor.setProvider(provider); +const providerEphemeralRollup = new anchor.AnchorProvider( + new anchor.web3.Connection("https://devnet-as.magicblock.app/", { + wsEndpoint: "wss://devnet.magicblock.app/", + }), + anchor.Wallet.local() +); + +// Set program and pda +const program = anchor.workspace.AnchorCounter as Program; +const [pda] = anchor.web3.PublicKey.findProgramAddressSync( + [Buffer.from(SEED_TEST_PDA)], + program.programId +); + +// Initialize Counter on Base Layer +let initTx = await program.methods + .increment() + .accounts({ + counter: pda, + }) + .transaction(); +initTx.feePayer = provider.wallet.publicKey; +initTx.recentBlockhash = ( + await provider.connection.getLatestBlockhash() +).blockhash; +initTx = await provider.connection.signTransaction(initTx); +const dinitTxHash = await provider.sendAndConfirm(initTx); + +// Delegate Counter on Base Layer to ER +let delTx = await program.methods + .increment() + .accounts({ + counter: pda, + }) + .transaction(); +delTx.feePayer = provider.connection.wallet.publicKey; +delTx.recentBlockhash = ( + await provider.connection.getLatestBlockhash() +).blockhash; +delTx = await provider.wallet.signTransaction(delTx); +const delTxHash = await provider.sendAndConfirm(delTx); + +// Increment Counter in real-time on ER +let incTx = await program.methods + .increment() + .accounts({ + counter: pda, + }) + .transaction(); +incTx.feePayer = providerEphemeralRollup.wallet.publicKey; +incTx.recentBlockhash = ( + await providerEphemeralRollup.connection.getLatestBlockhash() +).blockhash; +incTx = await providerEphemeralRollup.wallet.signTransaction(incTx); +const incTxHash = await providerEphemeralRollup.sendAndConfirm(incTx); +``` + +To make it easier to integrate via the frontend, we created the [Magic Router](/pages/ephemeral-rollups-ers/introduction/magic-router). You send transactions directly to the magic router, and we can determine for you whether it should be routed to the [Ephemeral Rollup](/pages/ephemeral-rollups-ers/introduction/ephemeral-rollup) or base layer. + + diff --git a/pages/ephemeral-rollups-ers/how-to-guide/rust.mdx b/pages/ephemeral-rollups-ers/how-to-guide/rust.mdx new file mode 100644 index 0000000..5e7275f --- /dev/null +++ b/pages/ephemeral-rollups-ers/how-to-guide/rust.mdx @@ -0,0 +1,639 @@ +--- +title: "Rust Example" +description: "Learn how to write a simple Rust program that delegates and increments a counter on Solana" +--- + +import Endpoints from "/snippets/endpoints.mdx"; + +
+