xyqon 0.4.0 → 0.5.0

package/README.md

@@ -20,12 +20,30 @@ You do not need to mine and you do not need to run a full node.
 npm install -g xyqon
 ```
 
+Update an existing global install:
+
+```bash
+npm update -g xyqon
+```
+
+Or install this exact release:
+
+```bash
+npm install -g xyqon@0.5.0
+```
+
 Or run without installing:
 
 ```bash
 npx xyqon help
 ```
 
+Run this exact release without installing:
+
+```bash
+npx xyqon@0.5.0 help
+```
+
 ## Create A Wallet
 
 ```bash
@@ -67,7 +85,8 @@ xyqon send \
 ```
 
 The transaction is broadcast to reachable public nodes. A miner must include it in a block before the receiver sees the confirmed balance.
-The client checks the best reachable public chain before broadcasting and refuses sends that exceed the wallet's confirmed XYQON balance.
+The client checks the best reachable public chain before broadcasting, refuses sends that exceed the wallet's confirmed XYQON balance, and now requires at least one node to verify the transaction as pending or confirmed before returning success.
+If every reachable node rejects the transaction or cannot return a transaction status, the send fails with the node's rejection reason when available.
 
 ## Create And Send Coins
 
@@ -107,6 +126,13 @@ xyqon nft send \
 xyqon nodes
 ```
 
+## Show Version
+
+```bash
+xyqon version
+xyqon -v
+```
+
 ## Seed Nodes
 
 The package starts with these seed nodes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xyqon",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Friendly wallet CLI and JavaScript client for the XYQON network.",
   "keywords": [
     "xyqon",

package/src/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from 'node:module';
 import {
   DEFAULT_PEERS,
   DEFAULT_WALLET_PATH,
@@ -15,6 +16,9 @@ import {
   sendTransaction
 } from './index.js';
 
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require('../package.json');
+
 const colors = {
   cyan: '\x1b[36m',
   green: '\x1b[32m',
@@ -48,6 +52,8 @@ ${color('bold', 'Usage')}
   xyqon nft mint --collection <SYMBOL> --token-id <ID> --name <NAME> [--image-url <URL>] [--wallet <FILE>]
   xyqon nft send --collection <SYMBOL> --token-id <ID> --to <PUBLIC_KEY> [--wallet <FILE>]
   xyqon nodes
+  xyqon version
+  xyqon -v
 
 ${color('bold', 'Network options')}
   --peer <IP[:PORT]>    Add a seed peer. Can be repeated.
@@ -58,6 +64,16 @@ ${color('bold', 'Defaults')}
 `);
 }
 
+function printDelivery(result, label = 'Delivered') {
+  console.log(`${color('green', `${label}:`)} ${result.verifiedBy}/${result.peers.length} nodes verified pending or confirmed`);
+  if (result.rejectedBy > 0) {
+    console.log(`${color('red', 'Rejected:')} ${result.rejectedBy}/${result.peers.length} nodes`);
+  }
+  if (result.unverifiedBy > 0) {
+    console.log(`${color('yellow', 'Unverified:')} ${result.unverifiedBy}/${result.peers.length} nodes did not return a transaction status`);
+  }
+}
+
 function parseArgs(argv) {
   const values = { _: [] };
   for (let index = 0; index < argv.length; index += 1) {
@@ -105,6 +121,11 @@ async function run() {
     return;
   }
 
+  if (command === 'version' || command === '--version' || command === '-v') {
+    console.log(VERSION);
+    return;
+  }
+
   if (command === 'wallet' && subcommand === 'new') {
     const path = options.out ?? DEFAULT_WALLET_PATH;
     const wallet = createWallet(options.name ?? 'XYQON User');
@@ -162,7 +183,7 @@ async function run() {
     console.log(`${color('bold', 'To:')} ${result.transaction.recipient}`);
     console.log(`${color('bold', 'Transaction ID:')} ${result.transactionId}`);
     console.log(`${color('dim', 'Checked balance:')} ${result.preflight.balance} XYQON at block ${result.preflight.blockHeight}`);
-    console.log(`${color('green', 'Delivered:')} ${result.acceptedBy}/${result.peers.length} reachable nodes`);
+    printDelivery(result);
     console.log(color('yellow', 'The receiver balance updates after a miner includes this transaction in a block.'));
     return;
   }
@@ -191,7 +212,7 @@ async function run() {
     console.log(`${color('bold', 'Symbol:')} ${result.transaction.asset_operation.CreateCoin.symbol}`);
     console.log(`${color('bold', 'Supply:')} ${result.transaction.asset_operation.CreateCoin.supply}`);
     console.log(`${color('bold', 'Transaction ID:')} ${result.transactionId}`);
-    console.log(`${color('green', 'Broadcast:')} ${result.acceptedBy}/${result.peers.length} reachable nodes`);
+    printDelivery(result, 'Broadcast');
     console.log(color('yellow', 'The coin exists after a miner includes this transaction in a block.'));
     return;
   }
@@ -221,7 +242,7 @@ async function run() {
     console.log(`${color('bold', 'To:')} ${result.transaction.recipient}`);
     console.log(`${color('bold', 'Transaction ID:')} ${result.transactionId}`);
     console.log(`${color('dim', 'Checked balance:')} ${result.preflight.balance} ${result.preflight.symbol} at block ${result.preflight.blockHeight}`);
-    console.log(`${color('green', 'Delivered:')} ${result.acceptedBy}/${result.peers.length} reachable nodes`);
+    printDelivery(result);
     return;
   }
 
@@ -249,7 +270,7 @@ async function run() {
     printHero('NFT Minted');
     console.log(`${color('bold', 'NFT:')} ${result.transaction.asset_operation.MintNft.collection}:${result.transaction.asset_operation.MintNft.token_id}`);
     console.log(`${color('bold', 'Transaction ID:')} ${result.transactionId}`);
-    console.log(`${color('green', 'Broadcast:')} ${result.acceptedBy}/${result.peers.length} reachable nodes`);
+    printDelivery(result, 'Broadcast');
     console.log(color('yellow', 'The NFT exists after a miner includes this transaction in a block.'));
     return;
   }
@@ -278,7 +299,7 @@ async function run() {
     console.log(`${color('bold', 'NFT:')} ${result.transaction.asset_operation.TransferNft.collection}:${result.transaction.asset_operation.TransferNft.token_id}`);
     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`);
+    printDelivery(result, 'Broadcast');
     return;
   }
 

package/src/index.js

@@ -334,6 +334,62 @@ export function sendNetworkMessage(peer, message, timeoutMs = 5000) {
   });
 }
 
+export function sendTransactionMessage(peer, transaction, 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();
+    const id = transactionId(transaction);
+    let data = '';
+    let wrote = false;
+    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({ NewTransaction: transaction })}\n`, () => {
+        wrote = true;
+      });
+    });
+    socket.on('data', (chunk) => {
+      data += chunk.toString('utf8');
+      if (!data.includes('\n')) {
+        return;
+      }
+
+      try {
+        const parsed = JSON.parse(data.trim());
+        const status = parsed.TransactionResponse;
+        if (!status || status.id !== id) {
+          finish({ ok: false, submitted: wrote, error: 'peer returned an unexpected transaction response' });
+          return;
+        }
+
+        finish({
+          ok: status.status === 'pending' || status.status === 'confirmed',
+          submitted: status.status === 'pending' || status.status === 'confirmed',
+          verified: true,
+          status: status.status,
+          error: status.error ?? undefined
+        });
+      } catch (error) {
+        finish({ ok: false, submitted: wrote, error: error.message });
+      }
+    });
+    socket.on('timeout', () => finish({ ok: false, submitted: wrote, verified: false, error: 'timeout waiting for transaction response' }));
+    socket.on('error', (error) => finish({ ok: false, submitted: wrote, error: error.message }));
+  });
+}
+
 export async function requestChain(peer) {
   const result = await requestMessage(peer, 'RequestChain', 'ChainResponse');
   return { ...result, chain: result.payload };
@@ -347,6 +403,16 @@ export async function requestPeers(peer) {
   };
 }
 
+export async function requestTransactionStatus(peer, id) {
+  const result = await requestMessage(peer, { RequestTransaction: id }, 'TransactionResponse');
+  return {
+    ...result,
+    transaction: result.payload,
+    status: result.payload?.status,
+    verified: result.ok && (result.payload?.status === 'pending' || result.payload?.status === 'confirmed')
+  };
+}
+
 export async function discoverPeers(seedPeers = DEFAULT_PEERS) {
   const discovered = new Set(normalizePeers(seedPeers));
   let frontier = [...discovered];
@@ -626,32 +692,50 @@ export async function getCoinHoldings(addressOrWallet, seedPeers = DEFAULT_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)));
+  const id = transactionId(transaction);
+  const results = await Promise.all(peers.map((peer) => sendTransactionMessage(peer, transaction)));
+  const verifiedResults = results.filter((result) => result.verified);
+  const rejectedResults = results.filter((result) => result.status === 'rejected');
 
   return {
-    transactionId: transactionId(transaction),
+    transactionId: id,
     peers,
     results,
-    acceptedBy: results.filter((result) => result.ok).length
+    acceptedBy: verifiedResults.length,
+    verifiedBy: verifiedResults.length,
+    rejectedBy: rejectedResults.length,
+    unverifiedBy: results.filter((result) => result.submitted && !result.verified).length
   };
 }
 
+function assertBroadcastVerified(broadcast) {
+  if (broadcast.verifiedBy > 0) {
+    return broadcast;
+  }
+
+  const rejection = broadcast.results.find((result) => result.status === 'rejected' && result.error);
+  const failure = rejection ?? broadcast.results.find((result) => result.error);
+  const detail = failure ? ` ${failure.peer}: ${failure.error}` : '';
+  throw new Error(`transaction was not accepted by any reachable XYQON node.${detail}`);
+}
+
 export async function sendTransaction({ wallet, recipient, amount, fee = DEFAULT_XYQON_TRANSACTION_FEE, peers = DEFAULT_PEERS }) {
   const transaction = createSignedTransaction(wallet, recipient, amount, fee);
   const preflight = await assertSpendableXyqonBalance(wallet, transaction.amount, peers, transaction.fee);
+  const broadcast = assertBroadcastVerified(await broadcastTransaction(transaction, peers));
   return {
     transaction,
     preflight,
-    ...(await broadcastTransaction(transaction, peers))
+    ...broadcast
   };
 }
 
 export async function createCoin({ wallet, symbol, name, supply, peers = DEFAULT_PEERS }) {
   const transaction = createCoinTransaction(wallet, { symbol, name, supply });
+  const broadcast = assertBroadcastVerified(await broadcastTransaction(transaction, peers));
   return {
     transaction,
-    ...(await broadcastTransaction(transaction, peers))
+    ...broadcast
   };
 }
 
@@ -663,25 +747,28 @@ export async function sendCoin({ wallet, recipient, symbol, amount, peers = DEFA
     transaction.asset_operation.TransferCoin.amount,
     peers
   );
+  const broadcast = assertBroadcastVerified(await broadcastTransaction(transaction, peers));
   return {
     transaction,
     preflight,
-    ...(await broadcastTransaction(transaction, peers))
+    ...broadcast
   };
 }
 
 export async function mintNft({ wallet, collection, tokenId, name, imageUrl = null, peers = DEFAULT_PEERS }) {
   const transaction = createNftMintTransaction(wallet, { collection, tokenId, name, imageUrl });
+  const broadcast = assertBroadcastVerified(await broadcastTransaction(transaction, peers));
   return {
     transaction,
-    ...(await broadcastTransaction(transaction, peers))
+    ...broadcast
   };
 }
 
 export async function transferNft({ wallet, recipient, collection, tokenId, peers = DEFAULT_PEERS }) {
   const transaction = createNftTransferTransaction(wallet, { recipient, collection, tokenId });
+  const broadcast = assertBroadcastVerified(await broadcastTransaction(transaction, peers));
   return {
     transaction,
-    ...(await broadcastTransaction(transaction, peers))
+    ...broadcast
   };
 }