DocsSDK Reference

SDK Reference

Interact with the FractalAI blockchain via JSON-RPC. Examples in Rust, TypeScript, and curl.

Connecting to a Node

Connect to a FractalAI node via its JSON-RPC endpoint. The default port is 9545.

main.rs
use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let rpc_url = "http://localhost:9545";

    // Test connection - get current block number
    let response = client
        .post(rpc_url)
        .json(&json!({
            "jsonrpc": "2.0",
            "method": "eth_blockNumber",
            "params": [],
            "id": 1
        }))
        .send()
        .await?;

    let result: serde_json::Value = response.json().await?;
    println!("Current block: {}", result["result"]);

    Ok(())
}

Querying Blocks

Fetch block data including fractal scores, transaction lists, and validator information.

Get Block Data
// Get latest block
let block = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "eth_getBlockByNumber",
        "params": ["latest", false],
        "id": 1
    }))
    .send()
    .await?
    .json::<serde_json::Value>()
    .await?;

let block = &block["result"];
println!("Block #{}", block["number"]);
println!("Hash: {}", block["hash"]);
println!("Parent: {}", block["parentHash"]);
println!("Fractal Score: {}", block["fractalScore"]);
println!("Transactions: {}", block["transactions"].as_array().map(|a| a.len()).unwrap_or(0));

// Get block by hash
let block_by_hash = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "eth_getBlockByHash",
        "params": [block["hash"], true],  // true = full tx objects
        "id": 2
    }))
    .send()
    .await?;

Accounts & Balances

Query account balances and nonces. Create wallets with post-quantum Dilithium keypairs.

Account Operations
// Get balance (returns wei as hex)
let balance = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "eth_getBalance",
        "params": ["0x1234...", "latest"],
        "id": 1
    }))
    .send()
    .await?
    .json::<serde_json::Value>()
    .await?;

println!("Balance: {} wei", balance["result"]);

// Get nonce (transaction count)
let nonce = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "eth_getTransactionCount",
        "params": ["0x1234...", "latest"],
        "id": 2
    }))
    .send()
    .await?;

// Create a new wallet (Dilithium keypair)
let wallet = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "fractal_createWallet",
        "params": ["my_secure_password"],
        "id": 3
    }))
    .send()
    .await?
    .json::<serde_json::Value>()
    .await?;

println!("New address: {}", wallet["result"]["address"]);

// Request testnet FRAC from faucet
let faucet = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "fractal_faucet",
        "params": [wallet["result"]["address"]],
        "id": 4
    }))
    .send()
    .await?;

Sending Transactions

Sign and submit transactions using Dilithium signatures. Transfer FRAC, stake tokens, or interact with smart contracts.

Sign & Send Transaction
// Sign a transaction using node-managed wallet
let signed_tx = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "fractal_signTransaction",
        "params": [{
            "from": "0x1234...",
            "to": "0x5678...",
            "value": "0xde0b6b3a7640000",  // 1 FRAC in wei
            "password": "my_secure_password"
        }],
        "id": 1
    }))
    .send()
    .await?
    .json::<serde_json::Value>()
    .await?;

let tx_hash = &signed_tx["result"]["tx_hash"];
println!("Transaction sent: {}", tx_hash);

// Wait for receipt
let receipt = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "eth_getTransactionReceipt",
        "params": [tx_hash],
        "id": 2
    }))
    .send()
    .await?
    .json::<serde_json::Value>()
    .await?;

println!("Status: {}", receipt["result"]["status"]);
println!("Gas used: {}", receipt["result"]["gasUsed"]);

Validator Operations

Control mining, query validators, and monitor fractal challenges.

Mining & Validation
// Start mining
let start = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "fractal_startMining",
        "params": [],
        "id": 1
    }))
    .send()
    .await?;

println!("Mining started");

// Get current fractal challenge
let challenge = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "fractal_getChallenge",
        "params": [],
        "id": 2
    }))
    .send()
    .await?
    .json::<serde_json::Value>()
    .await?;

let challenge = &challenge["result"];
println!("Target dimension: {}", challenge["parameters"]["target_dimension"]);
println!("Difficulty: {}", challenge["parameters"]["difficulty"]);

// List active validators
let validators = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "fractal_getValidators",
        "params": [],
        "id": 3
    }))
    .send()
    .await?
    .json::<serde_json::Value>()
    .await?;

if let Some(vals) = validators["result"].as_array() {
    for v in vals {
        println!(
            "Validator {} | Score: {} | Blocks: {}",
            v["address"], v["fractal_score"], v["blocks_validated"]
        );
    }
}

// Stop mining
let stop = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "fractal_stopMining",
        "params": [],
        "id": 4
    }))
    .send()
    .await?;

AI Compute Jobs

Submit AI compute jobs to the network and retrieve results with fractal quality scores.

Submit & Query Jobs
// Submit an AI compute job
let job = client
    .post(rpc_url)
    .json(&json!({
        "jsonrpc": "2.0",
        "method": "fractal_submitJob",
        "params": [{
            "model": "fractal-v1",
            "input": { "prompt": "Explain quantum computing" },
            "max_gas": "0x100000"
        }],
        "id": 1
    }))
    .send()
    .await?
    .json::<serde_json::Value>()
    .await?;

let job_id = &job["result"]["job_id"];
println!("Job submitted: {}", job_id);

// Poll for result
loop {
    let result = client
        .post(rpc_url)
        .json(&json!({
            "jsonrpc": "2.0",
            "method": "fractal_getJob",
            "params": [job_id],
            "id": 2
        }))
        .send()
        .await?
        .json::<serde_json::Value>()
        .await?;

    let status = result["result"]["status"].as_str().unwrap_or("");
    if status == "completed" {
        println!("Output: {}", result["result"]["result"]["output"]);
        println!("Fractal score: {}", result["result"]["fractal_score"]);
        println!("Gas used: {}", result["result"]["gas_used"]);
        break;
    }

    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
}

Key Concepts

Dilithium Signatures

All transactions are signed with CRYSTALS-Dilithium, a post-quantum digital signature scheme. Public keys are 1,312 bytes and signatures are 2,420 bytes.

Fractal Scoring

Validators earn rewards based on how close their fractal dimension approaches the golden ratio (phi = 1.618033...). Higher scores earn proportionally more block rewards.

Gas & Fees

Transactions consume gas priced in FRAC. Use eth_estimateGas to estimate costs and eth_gasPrice for current pricing.

Block Time

Target block time is ~3 seconds. Blocks contain transaction lists, fractal scores, and validator public keys for verification.