@x1scroll/node-cli 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+# @x1scroll/node-cli
+
+CLI for registering X1 validators as storage nodes in the [x1scroll](https://x1scroll.io) network.
+
+## Installation
+
+```bash
+npm install -g @x1scroll/node-cli
+```
+
+## Usage
+
+### Register your validator as a storage node
+
+```bash
+x1scroll-node register \
+  --keypair ~/.config/solana/identity.json \
+  --ipfs-peer 12D3KooW... \
+  --endpoint https://your-node.com/api/ipfs/upload
+```
+
+### Update node info
+
+```bash
+x1scroll-node update \
+  --keypair ~/.config/solana/identity.json \
+  --ipfs-peer 12D3KooW... \
+  --endpoint https://your-node.com/api/ipfs/upload
+```
+
+### Deregister your node
+
+```bash
+x1scroll-node deregister --keypair ~/.config/solana/identity.json
+```
+
+> ⏳ Note: Deregistration starts a 2-day cooldown before it is finalized on-chain.
+
+### Check status
+
+```bash
+x1scroll-node status --keypair ~/.config/solana/identity.json
+```
+
+### List all registered nodes
+
+```bash
+x1scroll-node list
+```
+
+## Options
+
+All commands accept an optional `--rpc <url>` flag to override the default RPC endpoint (`https://rpc.x1.xyz`).
+
+```bash
+x1scroll-node list --rpc https://my-custom-rpc.example.com
+```
+
+## Details
+
+- **Network:** X1 (SVM-compatible)
+- **Program ID:** `GqzvCjz8nzxWxH39twk4oPfFaHXeyVDty9oJ6F4UcfF5`
+- **Registration fee:** 0.01 XNT
+- **PDA seeds:** `["storage_node", validator_pubkey]`
+
+## Requirements
+
+- Node.js >= 16
+- A funded X1 validator identity keypair (at least 0.01 XNT for registration)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const registry = require('../src/registry.js');
+
+const program = new Command();
+
+program
+  .name('x1scroll-node')
+  .description('CLI for managing x1scroll storage node registration on the X1 network')
+  .version('1.0.0');
+
+program
+  .command('register')
+  .description('Register a validator as a storage node')
+  .requiredOption('--keypair <path>', 'Path to validator keypair JSON file')
+  .requiredOption('--ipfs-peer <id>', 'IPFS peer ID (e.g. 12D3KooW...)')
+  .requiredOption('--endpoint <url>', 'Storage node endpoint URL')
+  .option('--rpc <url>', 'RPC endpoint', 'https://rpc.x1.xyz')
+  .action(async (opts) => {
+    try {
+      await registry.register(opts.keypair, opts.ipfsPeer, opts.endpoint, opts.rpc);
+    } catch (err) {
+      console.error(`❌ ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('update')
+  .description('Update storage node IPFS peer or endpoint')
+  .requiredOption('--keypair <path>', 'Path to validator keypair JSON file')
+  .requiredOption('--ipfs-peer <id>', 'New IPFS peer ID')
+  .requiredOption('--endpoint <url>', 'New storage node endpoint URL')
+  .option('--rpc <url>', 'RPC endpoint', 'https://rpc.x1.xyz')
+  .action(async (opts) => {
+    try {
+      await registry.update(opts.keypair, opts.ipfsPeer, opts.endpoint, opts.rpc);
+    } catch (err) {
+      console.error(`❌ ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('deregister')
+  .description('Deregister storage node (sets active=false, 2-day cooldown)')
+  .requiredOption('--keypair <path>', 'Path to validator keypair JSON file')
+  .option('--rpc <url>', 'RPC endpoint', 'https://rpc.x1.xyz')
+  .action(async (opts) => {
+    try {
+      await registry.deregister(opts.keypair, opts.rpc);
+    } catch (err) {
+      console.error(`❌ ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('status')
+  .description('Show registration status for a validator')
+  .requiredOption('--keypair <path>', 'Path to validator keypair JSON file')
+  .option('--rpc <url>', 'RPC endpoint', 'https://rpc.x1.xyz')
+  .action(async (opts) => {
+    try {
+      await registry.status(opts.keypair, opts.rpc);
+    } catch (err) {
+      console.error(`❌ ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list')
+  .description('List all registered storage nodes')
+  .option('--rpc <url>', 'RPC endpoint', 'https://rpc.x1.xyz')
+  .action(async (opts) => {
+    try {
+      await registry.list(opts.rpc);
+    } catch (err) {
+      console.error(`❌ ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@x1scroll/node-cli",
+  "version": "1.0.0",
+  "description": "CLI for registering X1 validators as storage nodes in the x1scroll network",
+  "bin": {
+    "x1scroll-node": "./bin/cli.js"
+  },
+  "main": "./bin/cli.js",
+  "license": "MIT",
+  "dependencies": {
+    "@solana/web3.js": "^1.98.0",
+    "commander": "^12.0.0"
+  }
+}

package/src/borsh.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Borsh encoding helpers
+ * String: 4-byte LE u32 length prefix + UTF-8 bytes
+ */
+
+function encodeString(str) {
+  const bytes = Buffer.from(str, 'utf8');
+  const len = Buffer.alloc(4);
+  len.writeUInt32LE(bytes.length, 0);
+  return Buffer.concat([len, bytes]);
+}
+
+function decodeString(buf, offset) {
+  const len = buf.readUInt32LE(offset);
+  offset += 4;
+  const str = buf.slice(offset, offset + len).toString('utf8');
+  return { value: str, offset: offset + len };
+}
+
+function encodeBool(val) {
+  const b = Buffer.alloc(1);
+  b.writeUInt8(val ? 1 : 0, 0);
+  return b;
+}
+
+function decodeBool(buf, offset) {
+  const val = buf.readUInt8(offset) !== 0;
+  return { value: val, offset: offset + 1 };
+}
+
+function decodeU64(buf, offset) {
+  // Read as two 32-bit LE values (low, high)
+  const lo = buf.readUInt32LE(offset);
+  const hi = buf.readUInt32LE(offset + 4);
+  const val = BigInt(hi) * BigInt(0x100000000) + BigInt(lo);
+  return { value: val, offset: offset + 8 };
+}
+
+function decodeI64(buf, offset) {
+  const lo = buf.readUInt32LE(offset);
+  const hi = buf.readInt32LE(offset + 4);
+  const val = BigInt(hi) * BigInt(0x100000000) + BigInt(lo);
+  return { value: val, offset: offset + 8 };
+}
+
+module.exports = {
+  encodeString,
+  decodeString,
+  encodeBool,
+  decodeBool,
+  decodeU64,
+  decodeI64,
+};

package/src/registry.js

@@ -0,0 +1,275 @@
+'use strict';
+
+const {
+  Connection,
+  PublicKey,
+  Keypair,
+  Transaction,
+  TransactionInstruction,
+  SystemProgram,
+  LAMPORTS_PER_SOL,
+} = require('@solana/web3.js');
+const crypto = require('crypto');
+const fs = require('fs');
+const borsh = require('./borsh.js');
+
+const PROGRAM_ID = new PublicKey('GqzvCjz8nzxWxH39twk4oPfFaHXeyVDty9oJ6F4UcfF5');
+const TREASURY = new PublicKey('HYP2VdVk2QNGKMBfWGFZpaFqMoqQkB7Vp5F12eSxCxtf');
+const DEFAULT_RPC = 'https://rpc.x1.xyz';
+const REGISTRATION_FEE = 0.01 * LAMPORTS_PER_SOL; // 0.01 XNT in lamports
+
+// Compute 8-byte discriminator: sha256("global:<name>")[0..8]
+function discriminator(name) {
+  const hash = crypto.createHash('sha256').update(`global:${name}`).digest();
+  return hash.slice(0, 8);
+}
+
+const DISC_REGISTER = discriminator('register_storage_node');
+const DISC_UPDATE = discriminator('update_storage_node');
+const DISC_DEREGISTER = discriminator('deregister_storage_node');
+const DISC_STORAGE_NODE = discriminator('storage_node'); // account discriminator
+
+function loadKeypair(keypairPath) {
+  const resolved = keypairPath.replace(/^~/, process.env.HOME || '');
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Keypair file not found: ${keypairPath}`);
+  }
+  const raw = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+  return Keypair.fromSecretKey(Uint8Array.from(raw));
+}
+
+async function deriveStorageNodePDA(validatorPubkey) {
+  const [pda, bump] = await PublicKey.findProgramAddress(
+    [Buffer.from('storage_node'), validatorPubkey.toBuffer()],
+    PROGRAM_ID
+  );
+  return { pda, bump };
+}
+
+async function getConnection(rpc) {
+  return new Connection(rpc || DEFAULT_RPC, 'confirmed');
+}
+
+// Decode StorageNode account data
+function decodeStorageNode(data) {
+  // Skip 8-byte discriminator
+  let offset = 8;
+
+  // validator: Pubkey (32 bytes)
+  const validator = new PublicKey(data.slice(offset, offset + 32));
+  offset += 32;
+
+  // ipfs_peer_id: String
+  const ipfsResult = borsh.decodeString(data, offset);
+  const ipfs_peer_id = ipfsResult.value;
+  offset = ipfsResult.offset;
+
+  // endpoint: String
+  const endpointResult = borsh.decodeString(data, offset);
+  const endpoint = endpointResult.value;
+  offset = endpointResult.offset;
+
+  // active: bool
+  const activeResult = borsh.decodeBool(data, offset);
+  const active = activeResult.value;
+  offset = activeResult.offset;
+
+  // total_pins: u64
+  const pinsResult = borsh.decodeU64(data, offset);
+  const total_pins = pinsResult.value;
+  offset = pinsResult.offset;
+
+  // registered_at: i64
+  const regResult = borsh.decodeI64(data, offset);
+  const registered_at = regResult.value;
+  offset = regResult.offset;
+
+  // last_active: i64
+  const lastResult = borsh.decodeI64(data, offset);
+  const last_active = lastResult.value;
+  offset = lastResult.offset;
+
+  return { validator, ipfs_peer_id, endpoint, active, total_pins, registered_at, last_active };
+}
+
+async function register(keypairPath, ipfsPeer, endpoint, rpc) {
+  const connection = await getConnection(rpc);
+  const keypair = loadKeypair(keypairPath);
+  const { pda } = await deriveStorageNodePDA(keypair.publicKey);
+
+  // Check if already registered
+  const existing = await connection.getAccountInfo(pda);
+  if (existing) {
+    throw new Error("Already registered. Use 'update' to change settings.");
+  }
+
+  // Check balance
+  const balance = await connection.getBalance(keypair.publicKey);
+  if (balance < REGISTRATION_FEE + 5000) {
+    throw new Error('Need at least 0.01 XNT for registration fee');
+  }
+
+  // Build instruction data
+  const ipfsBuf = borsh.encodeString(ipfsPeer);
+  const endpointBuf = borsh.encodeString(endpoint);
+  const data = Buffer.concat([DISC_REGISTER, ipfsBuf, endpointBuf]);
+
+  const instruction = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: keypair.publicKey, isSigner: true, isWritable: true },
+      { pubkey: pda, isSigner: false, isWritable: true },
+      { pubkey: TREASURY, isSigner: false, isWritable: true },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ],
+    data,
+  });
+
+  const tx = new Transaction().add(instruction);
+  const sig = await connection.sendTransaction(tx, [keypair]);
+  await connection.confirmTransaction(sig, 'confirmed');
+
+  console.log(`✅ Registered`);
+  console.log(`   Validator : ${keypair.publicKey.toBase58()}`);
+  console.log(`   PDA       : ${pda.toBase58()}`);
+  console.log(`   TX        : ${sig}`);
+}
+
+async function update(keypairPath, ipfsPeer, endpoint, rpc) {
+  const connection = await getConnection(rpc);
+  const keypair = loadKeypair(keypairPath);
+  const { pda } = await deriveStorageNodePDA(keypair.publicKey);
+
+  // Check if registered
+  const existing = await connection.getAccountInfo(pda);
+  if (!existing) {
+    throw new Error("Not registered. Use 'register' first.");
+  }
+
+  const ipfsBuf = borsh.encodeString(ipfsPeer);
+  const endpointBuf = borsh.encodeString(endpoint);
+  const data = Buffer.concat([DISC_UPDATE, ipfsBuf, endpointBuf]);
+
+  const instruction = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: keypair.publicKey, isSigner: true, isWritable: true },
+      { pubkey: pda, isSigner: false, isWritable: true },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ],
+    data,
+  });
+
+  const tx = new Transaction().add(instruction);
+  const sig = await connection.sendTransaction(tx, [keypair]);
+  await connection.confirmTransaction(sig, 'confirmed');
+
+  console.log(`✅ Updated`);
+  console.log(`   Validator : ${keypair.publicKey.toBase58()}`);
+  console.log(`   PDA       : ${pda.toBase58()}`);
+  console.log(`   TX        : ${sig}`);
+}
+
+async function deregister(keypairPath, rpc) {
+  const connection = await getConnection(rpc);
+  const keypair = loadKeypair(keypairPath);
+  const { pda } = await deriveStorageNodePDA(keypair.publicKey);
+
+  // Check if registered
+  const existing = await connection.getAccountInfo(pda);
+  if (!existing) {
+    throw new Error("Not registered. Use 'register' first.");
+  }
+
+  const data = Buffer.from(DISC_DEREGISTER);
+
+  const instruction = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: keypair.publicKey, isSigner: true, isWritable: true },
+      { pubkey: pda, isSigner: false, isWritable: true },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ],
+    data,
+  });
+
+  const tx = new Transaction().add(instruction);
+  const sig = await connection.sendTransaction(tx, [keypair]);
+  await connection.confirmTransaction(sig, 'confirmed');
+
+  console.log(`✅ Deregister requested`);
+  console.log(`   Validator : ${keypair.publicKey.toBase58()}`);
+  console.log(`   TX        : ${sig}`);
+  console.log(`   ⏳ 2-day cooldown before finalized`);
+}
+
+async function status(keypairPath, rpc) {
+  const connection = await getConnection(rpc);
+  const keypair = loadKeypair(keypairPath);
+  const { pda } = await deriveStorageNodePDA(keypair.publicKey);
+
+  const accountInfo = await connection.getAccountInfo(pda);
+  if (!accountInfo) {
+    console.log('Not registered');
+    return;
+  }
+
+  const node = decodeStorageNode(accountInfo.data);
+
+  const toDate = (ts) => {
+    if (ts === 0n) return 'never';
+    return new Date(Number(ts) * 1000).toISOString();
+  };
+
+  console.log('📡 Storage Node Status');
+  console.log(`   Validator   : ${node.validator.toBase58()}`);
+  console.log(`   PDA         : ${pda.toBase58()}`);
+  console.log(`   IPFS Peer   : ${node.ipfs_peer_id}`);
+  console.log(`   Endpoint    : ${node.endpoint}`);
+  console.log(`   Active      : ${node.active ? '✅ Yes' : '❌ No'}`);
+  console.log(`   Total Pins  : ${node.total_pins.toString()}`);
+  console.log(`   Registered  : ${toDate(node.registered_at)}`);
+  console.log(`   Last Active : ${toDate(node.last_active)}`);
+}
+
+async function list(rpc) {
+  const connection = await getConnection(rpc);
+
+  const accounts = await connection.getProgramAccounts(PROGRAM_ID, {
+    filters: [
+      {
+        memcmp: {
+          offset: 0,
+          bytes: Buffer.from(DISC_STORAGE_NODE).toString('base64'),
+          encoding: 'base64',
+        },
+      },
+    ],
+  });
+
+  if (accounts.length === 0) {
+    console.log('No registered storage nodes found.');
+    return;
+  }
+
+  console.log(`\n${'Validator'.padEnd(46)} ${'IPFS Peer'.padEnd(54)} ${'Endpoint'.padEnd(45)} ${'Active'.padEnd(7)} ${'Pins'}`);
+  console.log('-'.repeat(165));
+
+  for (const { pubkey, account } of accounts) {
+    try {
+      const node = decodeStorageNode(account.data);
+      const validator = node.validator.toBase58().padEnd(46);
+      const ipfs = (node.ipfs_peer_id || '').substring(0, 52).padEnd(54);
+      const ep = (node.endpoint || '').substring(0, 43).padEnd(45);
+      const active = (node.active ? '✅' : '❌').padEnd(7);
+      const pins = node.total_pins.toString();
+      console.log(`${validator} ${ipfs} ${ep} ${active} ${pins}`);
+    } catch (e) {
+      console.log(`[Could not decode account ${pubkey.toBase58()}]`);
+    }
+  }
+
+  console.log(`\nTotal: ${accounts.length} node(s)`);
+}
+
+module.exports = { register, update, deregister, status, list };