xyqon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XYQON
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# XYQON Client
+
+Friendly wallet CLI and JavaScript client for the live XYQON network.
+
+It can:
+
+- Generate a new XYQON wallet
+- Show your public key
+- Check your balance from live public nodes
+- Send a signed transaction to the network
+- Show currently reachable nodes
+
+You do not need to mine and you do not need to run a full node.
+
+## Install
+
+```bash
+npm install -g xyqon-client
+```
+
+Or run without installing:
+
+```bash
+npx xyqon-client help
+```
+
+## Create A Wallet
+
+```bash
+xyqon wallet new --name Cathy
+```
+
+This creates:
+
+```text
+xyqon.wallet.json
+```
+
+Keep this file private. It contains your private key.
+
+## Show Your Address
+
+```bash
+xyqon wallet show
+```
+
+## Check Balance
+
+```bash
+xyqon balance
+```
+
+Use a custom wallet path:
+
+```bash
+xyqon balance --wallet ./cathy.wallet.json
+```
+
+## Send XYQON
+
+```bash
+xyqon send \
+  --to RECIPIENT_PUBLIC_KEY \
+  --amount 1
+```
+
+The transaction is broadcast to reachable public nodes. A miner must include it in a block before the receiver sees the confirmed balance.
+
+## Show Nodes
+
+```bash
+xyqon nodes
+```
+
+## Seed Nodes
+
+The package starts with these seed nodes:
+
+```text
+68.183.98.134:7101
+143.244.149.8:7101
+147.182.138.183:7101
+```
+
+You can override them:
+
+```bash
+xyqon balance --peer 68.183.98.134:7101 --peer 143.244.149.8:7101
+```
+
+## JavaScript Usage
+
+```js
+import {
+  createWallet,
+  loadWallet,
+  getBalance,
+  sendTransaction
+} from 'xyqon-client';
+
+const wallet = createWallet('Cathy');
+console.log(wallet.public_key);
+
+const balance = await getBalance(wallet.public_key);
+console.log(balance);
+
+await sendTransaction({
+  wallet,
+  recipient: 'RECIPIENT_PUBLIC_KEY',
+  amount: 1
+});
+```

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "xyqon",
+  "version": "0.1.0",
+  "description": "Friendly wallet CLI and JavaScript client for the XYQON network.",
+  "keywords": [
+    "xyqon",
+    "wallet",
+    "blockchain",
+    "ed25519",
+    "cli"
+  ],
+  "homepage": "https://github.com/gideonlouw/xyqon#readme",
+  "bugs": {
+    "url": "https://github.com/gideonlouw/xyqon/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gideonlouw/xyqon.git"
+  },
+  "license": "MIT",
+  "author": "xyqon",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "main": "index.js",
+  "bin": {
+    "xyqon": "src/cli.js",
+    "xyqon-client": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "check": "node src/cli.js help && node src/cli.js nodes"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.8.2"
+  },
+  "devDependencies": {},
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/cli.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_PEERS,
+  DEFAULT_WALLET_PATH,
+  createWallet,
+  discoverPeers,
+  getBalance,
+  getBestChain,
+  loadWallet,
+  saveWallet,
+  sendTransaction
+} from './index.js';
+
+const colors = {
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  reset: '\x1b[0m'
+};
+
+function color(name, text) {
+  return `${colors[name]}${text}${colors.reset}`;
+}
+
+function printHero(title = 'XYQON Wallet') {
+  console.log(color('cyan', '╔════════════════════════════════════════════════════╗'));
+  console.log(color('cyan', `║ ${title.padEnd(50)} ║`));
+  console.log(color('cyan', '╚════════════════════════════════════════════════════╝'));
+}
+
+function printHelp() {
+  printHero('XYQON Client');
+  console.log(`
+${color('bold', 'Usage')}
+  xyqon wallet new --name <NAME> [--out <FILE>]
+  xyqon wallet show [--wallet <FILE>] [--private]
+  xyqon balance [--wallet <FILE>] [--address <PUBLIC_KEY>]
+  xyqon send --to <PUBLIC_KEY> --amount <AMOUNT> [--wallet <FILE>]
+  xyqon nodes
+
+${color('bold', 'Network options')}
+  --peer <IP[:PORT]>    Add a seed peer. Can be repeated.
+
+${color('bold', 'Defaults')}
+  Wallet: ${DEFAULT_WALLET_PATH}
+  Peers:  ${DEFAULT_PEERS.join(', ')}
+`);
+}
+
+function parseArgs(argv) {
+  const values = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith('--')) {
+      values._.push(item);
+      continue;
+    }
+
+    const key = item.slice(2);
+    if (key === 'private' || key === 'force') {
+      values[key] = true;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) {
+      throw new Error(`--${key} requires a value`);
+    }
+    index += 1;
+
+    if (key === 'peer') {
+      values.peer = [...(values.peer ?? []), value];
+    } else {
+      values[key] = value;
+    }
+  }
+
+  return values;
+}
+
+function peersFromOptions(options) {
+  return options.peer?.length ? options.peer : DEFAULT_PEERS;
+}
+
+async function run() {
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+  const subcommand = command === 'wallet' ? argv[1] : undefined;
+  const rest = command === 'wallet' ? argv.slice(2) : argv.slice(1);
+  const options = parseArgs(rest);
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (command === 'wallet' && subcommand === 'new') {
+    const path = options.out ?? DEFAULT_WALLET_PATH;
+    const wallet = createWallet(options.name ?? 'XYQON User');
+    await saveWallet(wallet, path);
+    printHero('Wallet Created');
+    console.log(`${color('green', 'Saved:')} ${path}`);
+    console.log(`${color('green', 'Public key:')} ${wallet.public_key}`);
+    console.log(color('yellow', 'Keep the wallet file private. It contains your private key.'));
+    return;
+  }
+
+  if (command === 'wallet' && subcommand === 'show') {
+    const wallet = await loadWallet(options.wallet ?? DEFAULT_WALLET_PATH);
+    printHero('Wallet');
+    console.log(`${color('bold', 'Name:')} ${wallet.name}`);
+    console.log(`${color('bold', 'Public key:')} ${wallet.public_key}`);
+    if (options.private) {
+      console.log(`${color('red', 'Private key:')} ${wallet.private_key}`);
+    }
+    return;
+  }
+
+  if (command === 'balance') {
+    const wallet = options.address ? null : await loadWallet(options.wallet ?? DEFAULT_WALLET_PATH);
+    const address = options.address ?? wallet.public_key;
+    const balance = await getBalance(address, peersFromOptions(options));
+    printHero('Balance');
+    console.log(`${color('bold', 'Address:')} ${balance.address}`);
+    console.log(`${color('green', 'Balance:')} ${balance.balance} XYQON`);
+    console.log(`${color('dim', 'Block height:')} ${balance.blockHeight}`);
+    console.log(`${color('dim', 'Source node:')} ${balance.sourcePeer}`);
+    return;
+  }
+
+  if (command === 'send') {
+    if (!options.to) {
+      throw new Error('send requires --to <PUBLIC_KEY>');
+    }
+    if (!options.amount) {
+      throw new Error('send requires --amount <AMOUNT>');
+    }
+
+    const wallet = await loadWallet(options.wallet ?? DEFAULT_WALLET_PATH);
+    const result = await sendTransaction({
+      wallet,
+      recipient: options.to,
+      amount: options.amount,
+      peers: peersFromOptions(options)
+    });
+
+    printHero('Transaction Sent');
+    console.log(`${color('bold', 'Amount:')} ${result.transaction.amount} XYQON`);
+    console.log(`${color('bold', 'To:')} ${result.transaction.recipient}`);
+    console.log(`${color('bold', 'Transaction ID:')} ${result.transactionId}`);
+    console.log(`${color('green', 'Broadcast:')} ${result.acceptedBy}/${result.peers.length} reachable nodes`);
+    console.log(color('yellow', 'The receiver balance updates after a miner includes this transaction in a block.'));
+    return;
+  }
+
+  if (command === 'nodes') {
+    const peers = await discoverPeers(peersFromOptions(options));
+    const { nodes, chain, sourcePeer } = await getBestChain(peers);
+    printHero('Live Nodes');
+    for (const node of nodes) {
+      const icon = node.ok ? color('green', '●') : color('red', '●');
+      console.log(`${icon} ${node.peer.padEnd(22)} ${node.ok ? `${node.latencyMs} ms` : node.error}`);
+    }
+    console.log('');
+    console.log(`${color('bold', 'Height:')} ${chain.chain.at(-1)?.index ?? 0}`);
+    console.log(`${color('bold', 'Supply:')} ${chain.circulating_supply} XYQON`);
+    console.log(`${color('dim', 'Best source:')} ${sourcePeer}`);
+    return;
+  }
+
+  throw new Error(`unknown command: ${[command, subcommand].filter(Boolean).join(' ')}`);
+}
+
+run().catch((error) => {
+  console.error(color('red', `Error: ${error.message}`));
+  process.exit(1);
+});

package/src/index.js

@@ -0,0 +1,275 @@
+import { ed25519 } from '@noble/curves/ed25519';
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import net from 'node:net';
+
+export const DEFAULT_PEERS = [
+  '68.183.98.134:7101',
+  '143.244.149.8:7101',
+  '147.182.138.183:7101'
+];
+
+export const DEFAULT_WALLET_PATH = 'xyqon.wallet.json';
+
+export function bytesToHex(bytes) {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+export function hexToBytes(hex) {
+  if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length % 2 !== 0) {
+    throw new Error('expected a valid hex string');
+  }
+
+  return Uint8Array.from(hex.match(/.{2}/g).map((part) => Number.parseInt(part, 16)));
+}
+
+export function normalizePeer(peer) {
+  const value = `${peer}`.split('#')[0].trim();
+  if (!value) {
+    return null;
+  }
+
+  return value.includes(':') ? value : `${value}:7101`;
+}
+
+export function normalizePeers(peers = DEFAULT_PEERS) {
+  return [...new Set(peers.map(normalizePeer).filter(Boolean))];
+}
+
+export function createWallet(name = 'XYQON User') {
+  const privateKey = ed25519.utils.randomPrivateKey();
+  const publicKey = ed25519.getPublicKey(privateKey);
+
+  return {
+    name,
+    public_key: bytesToHex(publicKey),
+    private_key: bytesToHex(privateKey)
+  };
+}
+
+export async function saveWallet(wallet, path = DEFAULT_WALLET_PATH) {
+  await writeFile(path, `${JSON.stringify(wallet, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function loadWallet(path = DEFAULT_WALLET_PATH) {
+  const wallet = JSON.parse(await readFile(path, 'utf8'));
+  if (!wallet.name || !wallet.public_key || !wallet.private_key) {
+    throw new Error(`wallet file is missing required fields: ${path}`);
+  }
+
+  return wallet;
+}
+
+export function transactionPayload(sender, recipient, amount, senderPublicKey) {
+  return `${sender}|${recipient}|${Number(amount).toFixed(8)}|${senderPublicKey}`;
+}
+
+export function createSignedTransaction(wallet, recipient, amount) {
+  const numericAmount = Number(amount);
+  if (!Number.isFinite(numericAmount) || numericAmount <= 0) {
+    throw new Error('amount must be a positive number');
+  }
+
+  const privateKey = hexToBytes(wallet.private_key);
+  const senderPublicKey = bytesToHex(ed25519.getPublicKey(privateKey));
+  if (senderPublicKey !== wallet.public_key) {
+    throw new Error('wallet public key does not match its private key');
+  }
+
+  const payload = transactionPayload(wallet.name, recipient, numericAmount, senderPublicKey);
+  const signature = ed25519.sign(new TextEncoder().encode(payload), privateKey);
+
+  return {
+    sender: wallet.name,
+    recipient,
+    amount: numericAmount,
+    sender_public_key: senderPublicKey,
+    signature: bytesToHex(signature)
+  };
+}
+
+export function transactionId(transaction) {
+  return createHash('sha256').update(JSON.stringify(transaction)).digest('hex');
+}
+
+export function requestMessage(peer, message, responseKey, timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    const normalizedPeer = normalizePeer(peer);
+    const [host, portText] = normalizedPeer.split(':');
+    const socket = net.createConnection({ host, port: Number(portText) });
+    const startedAt = Date.now();
+    let data = '';
+    let settled = false;
+
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      socket.destroy();
+      resolve({ peer: normalizedPeer, latencyMs: Date.now() - startedAt, ...result });
+    };
+
+    socket.setTimeout(timeoutMs);
+    socket.on('connect', () => socket.write(`${JSON.stringify(message)}\n`));
+    socket.on('data', (chunk) => {
+      data += chunk.toString('utf8');
+      if (!data.includes('\n')) {
+        return;
+      }
+
+      try {
+        const parsed = JSON.parse(data.trim());
+        finish({ ok: true, payload: parsed[responseKey] });
+      } catch (error) {
+        finish({ ok: false, error: error.message });
+      }
+    });
+    socket.on('timeout', () => finish({ ok: false, error: 'timeout' }));
+    socket.on('error', (error) => finish({ ok: false, error: error.message }));
+  });
+}
+
+export function sendNetworkMessage(peer, message, timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    const normalizedPeer = normalizePeer(peer);
+    const [host, portText] = normalizedPeer.split(':');
+    const socket = net.createConnection({ host, port: Number(portText) });
+    const startedAt = Date.now();
+    let settled = false;
+
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      socket.destroy();
+      resolve({ peer: normalizedPeer, latencyMs: Date.now() - startedAt, ...result });
+    };
+
+    socket.setTimeout(timeoutMs);
+    socket.on('connect', () => {
+      socket.write(`${JSON.stringify(message)}\n`, () => finish({ ok: true }));
+    });
+    socket.on('timeout', () => finish({ ok: false, error: 'timeout' }));
+    socket.on('error', (error) => finish({ ok: false, error: error.message }));
+  });
+}
+
+export async function requestChain(peer) {
+  const result = await requestMessage(peer, 'RequestChain', 'ChainResponse');
+  return { ...result, chain: result.payload };
+}
+
+export async function requestPeers(peer) {
+  const result = await requestMessage(peer, 'RequestPeers', 'PeerResponse');
+  return {
+    ...result,
+    peers: Array.isArray(result.payload) ? normalizePeers(result.payload) : []
+  };
+}
+
+export async function discoverPeers(seedPeers = DEFAULT_PEERS) {
+  const discovered = new Set(normalizePeers(seedPeers));
+  let frontier = [...discovered];
+
+  for (let depth = 0; depth < 2 && frontier.length > 0; depth += 1) {
+    const responses = await Promise.all(frontier.map((peer) => requestPeers(peer)));
+    const next = [];
+
+    for (const response of responses) {
+      if (!response.ok) {
+        continue;
+      }
+
+      for (const peer of response.peers) {
+        if (!discovered.has(peer)) {
+          discovered.add(peer);
+          next.push(peer);
+        }
+      }
+    }
+
+    frontier = next;
+  }
+
+  return [...discovered].sort();
+}
+
+export async function getBestChain(seedPeers = DEFAULT_PEERS) {
+  const peers = await discoverPeers(seedPeers);
+  const responses = await Promise.all(peers.map((peer) => requestChain(peer)));
+  const online = responses.filter((response) => response.ok && response.chain);
+
+  if (online.length === 0) {
+    throw new Error('no reachable XYQON nodes returned a chain');
+  }
+
+  online.sort((left, right) => chainScore(right.chain) - chainScore(left.chain));
+  return {
+    sourcePeer: online[0].peer,
+    peers,
+    nodes: responses,
+    chain: online[0].chain
+  };
+}
+
+export function chainScore(chain) {
+  return chain.chain.slice(1).reduce((score, block) => score + 2 ** Math.min(block.difficulty, 52), 0);
+}
+
+export function calculateBalances(chain) {
+  const balances = new Map();
+  const credit = (address, amount) => balances.set(address, (balances.get(address) ?? 0) + amount);
+  const debit = (address, amount) => balances.set(address, (balances.get(address) ?? 0) - amount);
+
+  for (const block of chain.chain.slice(1)) {
+    const [coinbase, ...transactions] = block.transactions;
+    if (coinbase?.recipient) {
+      credit(coinbase.recipient, coinbase.amount);
+    }
+
+    for (const transaction of transactions) {
+      debit(transaction.sender_public_key, transaction.amount);
+      credit(transaction.recipient, transaction.amount);
+    }
+  }
+
+  return balances;
+}
+
+export async function getBalance(addressOrWallet, seedPeers = DEFAULT_PEERS) {
+  const address = typeof addressOrWallet === 'string' ? addressOrWallet : addressOrWallet.public_key;
+  const { chain, sourcePeer, peers } = await getBestChain(seedPeers);
+  const balances = calculateBalances(chain);
+
+  return {
+    address,
+    balance: balances.get(address) ?? 0,
+    blockHeight: chain.chain.at(-1)?.index ?? 0,
+    circulatingSupply: chain.circulating_supply,
+    sourcePeer,
+    peers
+  };
+}
+
+export async function broadcastTransaction(transaction, seedPeers = DEFAULT_PEERS) {
+  const peers = await discoverPeers(seedPeers);
+  const message = { NewTransaction: transaction };
+  const results = await Promise.all(peers.map((peer) => sendNetworkMessage(peer, message)));
+
+  return {
+    transactionId: transactionId(transaction),
+    peers,
+    results,
+    acceptedBy: results.filter((result) => result.ok).length
+  };
+}
+
+export async function sendTransaction({ wallet, recipient, amount, peers = DEFAULT_PEERS }) {
+  const transaction = createSignedTransaction(wallet, recipient, amount);
+  return {
+    transaction,
+    ...(await broadcastTransaction(transaction, peers))
+  };
+}