Core SDK API Reference

The Core SDK (@magicblock-console/core) is the shared TypeScript library used by all three interfaces. You can also use it directly in your own applications.

Installation

npm install @magicblock-console/core

Configuration

createClient

Create a Console client instance.

import { createClient, FileStorage, MemoryStorage, BrowserStorage } from '@magicblock-console/core';

// CLI / Node.js
const client = createClient({
  network: 'devnet',
  storage: new FileStorage(),
});

// Connect with a Solana keypair for real blockchain operations
await client.connectWithKeypair('~/.config/solana/id.json');

// Web (browser)
const webClient = createClient({
  network: 'devnet',
  storage: new BrowserStorage(),
});

Options:

Call client.connectWithKeypair(path) to enable real blockchain operations. Without it, the SDK runs in simulated mode.

Projects

client.projects.create

const project = await client.projects.create({
  name: 'my-game',
  region: 'us',
  features: {
    gasless: true,
    privacy: false,
    vrf: true,
    cranks: false,
    oracle: false,
  },
});

Returns: Project

client.projects.list

const projects = await client.projects.list();

Returns: Project[]

client.projects.get

const project = await client.projects.get('my-game');

Returns: Project — throws if the project does not exist.

client.projects.configure

await client.projects.configure('my-game', {
  features: { vrf: true, cranks: true },
  region: 'eu', // optional — change project region
});

client.projects.delete

await client.projects.delete('my-game');

ER Lifecycle

client.er.delegate

Delegate an account to an Ephemeral Rollup.

const result = await client.er.delegate({
  account: 'AccountPublicKey...',
  project: 'my-game',
});

Returns: DelegationResult

interface DelegationResult {
  signature: string;
  validator: string;
  delegatedAt: Date;
  slot?: number;
  simulated: boolean;
}

client.er.status

Check delegation status.

const status = await client.er.status('AccountPublicKey...');

Returns: DelegationStatus

interface DelegationStatus {
  isDelegated: boolean;
  validator?: string;
  validatorPubkey?: string;
  delegatedAt?: Date;
}

client.er.commit

Commit ER state to base layer.

const result = await client.er.commit({
  account: 'AccountPublicKey...',
  project: 'my-game',
});

Returns: CommitResult

client.er.undelegate

Undelegate — final commit and return.

const result = await client.er.undelegate({
  account: 'AccountPublicKey...',
  project: 'my-game',
});

client.er.accounts

List delegated accounts in a project.

const accounts = await client.er.accounts('my-game');

Returns: DelegatedAccount[]

client.er.diff

Get state diff between ER and base layer.

const diff = await client.er.diff('AccountPublicKey...');

Returns: StateDiff

VRF

client.vrf.request

Request verifiable randomness.

const result = await client.vrf.request({ project: 'my-game' });

Returns: VrfResult

interface VrfResult {
  requestId: string;
  randomness: Uint8Array;
  proof: string;
  latencyMs: number;
  simulated: boolean;
}

VRF Utilities

Static utility functions for working with random bytes.

import { vrf } from '@magicblock-console/core';

// Random integer in range [min, max] inclusive
vrf.randomInRange(randomBytes: Uint8Array, min: number, max: number): number

// Pick random element from array
vrf.randomPick<T>(randomBytes: Uint8Array, items: T[]): T

// Split randomness into N independent values
vrf.split(randomBytes: Uint8Array, count: number): Uint8Array[]

Privacy

client.privacy.deposit

const result = await client.privacy.deposit({
  project: 'my-game',
  token: 'SOL',
  amount: 1.5,
  mint: 'So11111111111111111111111111111111111111112', // optional
});

Returns: PrivacyResult

interface PrivacyResult {
  signature: string;
  simulated: boolean;
}

client.privacy.transfer

const result = await client.privacy.transfer({
  project: 'my-game',
  token: 'USDC',
  amount: 50,
  to: 'RecipientWallet...',
});

Returns: PrivacyResult

client.privacy.withdraw

const result = await client.privacy.withdraw({
  project: 'my-game',
  token: 'SOL',
  amount: 0.5,
});

Returns: PrivacyResult

Cranks

client.cranks.create

const crank = await client.cranks.create({
  project: 'my-game',
  intervalMs: 5000,
  iterations: 100,
  account: 'AccountPublicKey...', // optional, enables real blockchain commits
});

Returns: Crank

interface Crank {
  id: string;
  intervalMs: number;
  iterations: number;
  executed: number;
  status: 'running' | 'completed' | 'stopped';
  account?: string;
  commitSignature?: string;
  simulated: boolean;
}

client.cranks.list

const cranks = await client.cranks.list('my-game');

client.cranks.stop

await client.cranks.stop('crank_id');

Oracle

client.oracle.getPrice

const price = await client.oracle.getPrice({
  project: 'my-game',
  feed: 'SOL/USD',
});

Returns: PriceFeed

interface PriceFeed {
  feed: string;
  price: number;
  confidence: number;
  timestamp: Date;
  slot: number;
  simulated: boolean;
}

Monitoring

client.monitor.status

const status = await client.monitor.status('my-game');

Returns: ProjectStatus

interface ProjectStatus {
  project: string;
  region: string;
  features: FeatureFlags;
  accounts: DelegatedAccount[];
  uptime: number;
  transactionCount: number;
}

client.monitor.costs

const costs = await client.monitor.costs('my-game');

Returns: CostBreakdown

interface CostBreakdown {
  transactions: { count: number; cost: number };
  commits: { count: number; cost: number };
  sessions: { count: number; cost: number };
  total: number;
  period: string;
}

client.monitor.logs

const logs = await client.monitor.logs('my-game', 50);

Returns: LogEntry[]

client.monitor.health

Ping all MagicBlock endpoints and return latency/status.

const endpoints = await client.monitor.health();

Returns: EndpointHealth[]

interface EndpointHealth {
  name: string;
  url: string;
  status: 'online' | 'offline';
  latencyMs: number | null;
}

Types

Project

interface Project {
  name: string;
  region: Region;
  features: FeatureFlags;
  createdAt: Date;
}

FeatureFlags

interface FeatureFlags {
  gasless: boolean;
  privacy: boolean;
  vrf: boolean;
  cranks: boolean;
  oracle: boolean;
}

Region

type Region = 'us' | 'eu' | 'asia';