@calldatasdk/server

Build your own backend on Ethereum. Listen for signed command transactions and run them.

This is the server half of Calldata Network. Users send signed JSON commands with the @calldatasdk/sdk client; this package scans blocks for those transactions (block subscription + poll safety net, so nothing is missed), then validates, authorizes and executes them.

npm install @calldatasdk/server ethers

A whole backend in a few lines

import { JsonRpcProvider } from 'ethers';
import { serve } from '@calldatasdk/server';
import { z } from 'zod';

const provider = new JsonRpcProvider('https://ethereum-sepolia-rpc.publicnode.com');

const sub = serve(provider, {
  openMode: true, // demo: accept any signer. Use allowlists in production.
  apps: [
    {
      namespace: 'board',
      controlAddress: '0xYOUR_APP_INBOX_ADDRESS',
      commands: {
        post: {
          schema: z.object({ text: z.string().max(280) }), // any { parse } works
          handler: (ctx) => board.add(ctx.signer, ctx.args.text),
        },
      },
    },
  ],
  onOutcome: (o) => console.log(o.namespace, o.cmd, o.status),
});

// later: await sub.stop();

Just the block primitive

If you want raw decoded commands and your own logic:

import { watchCommands } from '@calldatasdk/server';

const sub = watchCommands(provider, { controlAddresses: ['0xYOUR_APP_INBOX'] }, (cmd) => {
  // cmd = { txHash, signer, controlAddress, envelope: { cmd, args }, blockNumber }
  console.log(cmd.signer, 'sent', cmd.envelope.cmd, cmd.envelope.args);
});

What you get

• serve(provider, opts) , listener + interpreter wired together. Returns { stop() }.
• watchCommands(provider, opts, onCommand) , the block primitive: block subscription + poll backfill + dedupe + decode. Robust by design, a dropped event never loses a command.
• createInterpreter(opts) , routing, arg validation (any zod-compatible parse), role based authorization (fails closed), idempotency by transaction hash, serial execution per app.
• Re-exports decodeEnvelope, encodeEnvelope, isEnvelopeV1 from @calldatasdk/sdk.

How authorization works

• openMode: true accepts any signer (demo).
• Otherwise each app maps allowlist[signer] -> roles, and a command may require a role. Anything else is rejected. It fails closed.

ethers (v6) is a peer dependency. The signer of each transaction (tx.from) is the authenticated caller, no wallet connection anywhere.

Learn more at calldata.network. MIT licensed.