Code Examples

JavaScript/TypeScript

Send Priority Message

import { ethers } from "ethers";

async function sendPriorityMessage(content, bidAmount) {
  const provider = new ethers.JsonRpcProvider(process.env.OBSIDIAN_RPC_URL ?? "http://localhost:8545");
  const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

  const payload = "0x" + Buffer.from(content).toString("hex");
  const chainId = 421;
  const nonce = BigInt(Date.now());
  const targetBlock = 0;
  const bid = ethers.parseEther(bidAmount);

  // Create signature
  const bidHex = bid > 0n ? ethers.toBeHex(bid) : "0x";
  const signatureHash = ethers.keccak256(
    ethers.encodeRlp([
      ethers.toBeHex(chainId),
      ethers.toBeHex(targetBlock),
      ethers.toBeHex(nonce),
      wallet.address,
      payload,
      bidHex,
    ]),
  );
  const signature = await wallet.signMessage(ethers.getBytes(signatureHash));

  // Send with bid
  const result = await provider.send("eth_sendMessageBlob", [
    {
      from: wallet.address,
      data: payload,
      signature,
      targetBlock: ethers.toBeHex(targetBlock),
      nonce: ethers.toBeHex(nonce),
      chainId: ethers.toBeHex(chainId),
      bid: ethers.toBeHex(bid),
    },
  ]);

  return result;
}

// Usage
const hash = await sendPriorityMessage("Important update!", "0.01");

Send Free Message (with VDF)

/**
 * Compute checkpoint-based VDF proof.
 * Stores a checkpoint every √iterations steps.
 */
async function computeVdfCheckpoints(challenge, iterations) {
  const checkpointInterval = Math.floor(Math.sqrt(iterations));
  const checkpoints = [];
  let hash = challenge;

  for (let i = 0; i < iterations; i++) {
    // h_i = keccak256(h_{i-1} || i)
    const iterHex = i.toString(16).padStart(16, "0");
    hash = ethers.keccak256(hash + iterHex);

    // Store checkpoint at each interval
    if ((i + 1) % checkpointInterval === 0) {
      checkpoints.push(hash);
    }
  }

  // Always include final hash as last checkpoint
  if (iterations % checkpointInterval !== 0) {
    checkpoints.push(hash);
  }

  return { checkpoints, checkpointInterval };
}

async function sendFreeMessage(content) {
  const provider = new ethers.JsonRpcProvider(process.env.OBSIDIAN_RPC_URL ?? "http://localhost:8545");
  const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

  const payload = "0x" + Buffer.from(content).toString("hex");
  const chainId = 421;
  const nonce = BigInt(Date.now());
  const targetBlock = 0;

  // Get VDF work requirement
  const payloadBytes = Buffer.from(content).length;
  const work = await provider.send("eth_getMessageWork", [{ payloadSize: "0x" + payloadBytes.toString(16) }]);

  if (!work.enabled) {
    // VDF not required, submit without proof
    // (sign and send without vdf fields)
  }

  // Compute challenge = keccak256(rlp([chainId, sender, payload, nonce]))
  const challenge = ethers.keccak256(
    ethers.encodeRlp([ethers.toBeHex(chainId), wallet.address, payload, ethers.toBeHex(nonce)]),
  );

  // Compute VDF with checkpoints
  const requiredIterations = parseInt(work.requiredIterations, 16);
  const { checkpoints, checkpointInterval } = await computeVdfCheckpoints(challenge, requiredIterations);

  // Sign message
  const signatureHash = ethers.keccak256(
    ethers.encodeRlp([
      ethers.toBeHex(chainId),
      ethers.toBeHex(targetBlock),
      ethers.toBeHex(nonce),
      wallet.address,
      payload,
      "0x", // bid = 0 for SM (Standard Message)
    ]),
  );
  const signature = await wallet.signMessage(ethers.getBytes(signatureHash));

  // Send with VDF proof
  return await provider.send("eth_sendMessageBlob", [
    {
      from: wallet.address,
      data: payload,
      signature,
      targetBlock: ethers.toBeHex(targetBlock),
      nonce: ethers.toBeHex(nonce),
      chainId: ethers.toBeHex(chainId),
      bid: "0x0",
      vdfCheckpoints: checkpoints,
      vdfCheckpointInterval: ethers.toBeHex(checkpointInterval),
      vdfIterations: work.requiredIterations,
      vdfAlgVersion: work.algVersion,
    },
  ]);
}

Fetch Messages

async function getRecentMessages(blockCount = 10) {
  const provider = new ethers.JsonRpcProvider(process.env.OBSIDIAN_RPC_URL ?? "http://localhost:8545");

  const latest = await provider.getBlockNumber();
  const messages = [];

  for (let i = 0; i < blockCount; i++) {
    const blockNum = latest - i;
    const result = await provider.send("eth_getBlockMessages", ["0x" + blockNum.toString(16)]);
    messages.push(...(result || []));
  }

  return messages;
}

// Decode payload
function decodePayload(hexPayload) {
  return Buffer.from(hexPayload.slice(2), "hex").toString("utf8");
}

Check Buffer Status

async function checkBufferStatus() {
  const provider = new ethers.JsonRpcProvider(process.env.OBSIDIAN_RPC_URL ?? "http://localhost:8545");

  const status = await provider.send("eth_getMessageBufferStatus", []);

  // Note: pmPending, smPending are integers, not hex strings
  console.log("Lane count:", status.laneCount);
  console.log("PM pending:", status.pmPending);
  console.log("SM pending:", status.smPending);
  console.log("Top bid:", ethers.formatEther(BigInt(status.topBid || "0x0")), "OBS");

  return status;
}

Python

from web3 import Web3
from eth_account import Account
from eth_account.messages import encode_defunct
from eth_utils import keccak
import os
import rlp
import time

w3 = Web3(Web3.HTTPProvider(os.environ.get('OBSIDIAN_RPC_URL', 'http://localhost:8545')))

def send_message(private_key, content, bid_obs=None):
    account = Account.from_key(private_key)

    payload_bytes = content.encode()
    payload = '0x' + payload_bytes.hex()
    nonce_int = int(time.time() * 1000)
    chain_id_int = 421
    target_block_int = 0

    bid_wei = int((bid_obs or 0) * 10**18)
    bid_bytes = b"" if bid_wei == 0 else bid_wei.to_bytes((bid_wei.bit_length() + 7) // 8, "big")

    # signatureHash = keccak256(rlp([chainId, targetBlock, nonce, sender, payload, bidBytes]))
    sender_bytes = bytes.fromhex(account.address[2:])
    signature_hash = keccak(rlp.encode([
        chain_id_int,
        target_block_int,
        nonce_int,
        sender_bytes,
        payload_bytes,
        bid_bytes,
    ]))

    # Sign using EIP-191 personal_sign over the 32-byte signature hash
    signed = account.sign_message(encode_defunct(signature_hash))

    params = {
        'from': account.address,
        'data': payload,
        'signature': signed.signature.hex(),
        'targetBlock': hex(target_block_int),
        'nonce': hex(nonce_int),
        'chainId': hex(chain_id_int),
        'bid': hex(bid_wei),
        # If VDF is enabled on the network, also include:
        # vdfCheckpoints, vdfCheckpointInterval, vdfIterations, vdfAlgVersion
    }

    return w3.provider.make_request('eth_sendMessageBlob', [params])

cURL

# Get buffer status
curl -X POST ${OBSIDIAN_RPC_URL:-http://localhost:8545} \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getMessageBufferStatus","params":[],"id":1}'

# Get block messages
curl -X POST ${OBSIDIAN_RPC_URL:-http://localhost:8545} \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBlockMessages","params":["latest"],"id":1}'