@calldatasdk/sdk

Drive any backend on Ethereum with signed JSON commands. No wallet connection.

Calldata Network turns the Ethereum ledger into a programmable command bus: you put a small JSON command in a transaction's calldata and sign it. A Calldata backend scans those transactions, validates them, proves the signer from tx.from, and runs the matching handler. Every command is ordered, permanent and auditable.

This package is the client SDK: build, sign and send commands.

npm install @calldatasdk/sdk ethers

Quickstart (script / bot / agent)

Sign with your own Wallet and send. No connection, no session.

import { JsonRpcProvider, Wallet } from 'ethers';
import { sendCommand } from '@calldatasdk/sdk';

const provider = new JsonRpcProvider('https://ethereum-sepolia-rpc.publicnode.com');
const signer = new Wallet(process.env.PRIVATE_KEY!, provider);

const sent = await sendCommand(signer, {
  controlAddress: '0xCONTROL_ADDRESS_OF_THE_APP',
  cmd: 'post',
  args: { text: 'gm, on-chain' },
});

console.log('sent', sent.hash);
await sent.wait();

In the browser (any wallet, still no connect)

Build the transaction and hand it to a wallet to sign and send. The site never holds a session or your keys.

import { buildCommandTransaction } from '@calldatasdk/sdk';

const tx = buildCommandTransaction({
  controlAddress: '0xCONTROL_ADDRESS_OF_THE_APP',
  cmd: 'move',
  args: { x: 1, y: 2 },
});

const sent = await wallet.sendTransaction(tx); // ethers Signer / injected wallet

The command envelope (v1, frozen)

{
  "v": 1,                    // protocol version, always 1
  "cmd": "post",             // command name, 1..64 chars
  "args": { "text": "gm" },  // optional, validated per command
  "nonce": "8f3ad9c1",       // optional
  "exp": 1719250000          // optional unix seconds, rejected if in the past
}

import { encodeEnvelope, decodeEnvelope, encodeCommandData } from '@calldatasdk/sdk';

const json = encodeEnvelope({ cmd: 'post', args: { text: 'gm' } });
const data = encodeCommandData(json);   // -> 0x... calldata for the transaction
const envelope = decodeEnvelope(json);  // -> { v: 1, cmd: 'post', args: { text: 'gm' } }

API

• sendCommand(signer, input) , build, sign with an ethers Signer, and send. Returns the TransactionResponse.
• buildCommandTransaction(input) , build an unsigned TransactionRequest ({ to, data, value }) to sign with any wallet.
• encodeCommandData(json) / decodeCommandData(data) , envelope JSON <-> 0x calldata.
• encodeEnvelope(input) / decodeEnvelope(text) / isEnvelopeV1(x) , the v1 envelope.
• ENVELOPE_VERSION, MAX_COMMAND_BYTES.

ethers (v6) is a peer dependency.

Notes

• A command transaction is sent to the app's control address with the envelope JSON in its calldata. The raw calldata is the message: no contract, no ABI, no event.
• The signer of the transaction (tx.from) is the authenticated caller.
• Keep payloads small: calldata is paid for per byte, and the envelope is limited to 4096 bytes.

Learn more at calldata.network. MIT licensed.