nebulon-escrow-cli 0.8.4 → 0.8.5

package/README.md

@@ -1,14 +1,105 @@
 # Nebulon CLI
 
-Local development:
+Nebulon CLI is the command-line interface for managing Nebulon escrow contracts,
+wallets, capsules, and hosted profile actions. It supports MagicBlock ephemeral
+rollups for contract operations and provides end-to-end contract workflows,
+including terms, milestones, funding, and claims.
 
+## Requirements
+
+- Node.js 18 or newer
+- npm 9 or newer
+
+## Installation
+
+Global install from npm:
+
+```bash
+npm install -g nebulon-escrow-cli
 ```
+
+From source:
+
+```bash
 cd CLI
 npm install
 npm link
+```
+
+## Quick start
+
+```bash
 nebulon init
+nebulon login
+nebulon status
+```
+
+The `init` flow sets up a capsule, wallet, and network defaults. `login` connects
+to hosted services. Use `status` to verify connectivity and balances.
+
+## Command overview
+
+Run `nebulon help` for the full list. Common commands:
+
+- `nebulon init` - interactive setup (banner shows the CLI version)
+- `nebulon status` - account summary
+- `nebulon login` / `nebulon logout`
+- `nebulon capsule list` / `nebulon capsule use <name>`
+- `nebulon contract ...` - create and manage escrow contracts
+- `nebulon invite list` / `nebulon invite <id>`
+- `nebulon balance` / `nebulon address`
+- `nebulon wallet export`
+- `nebulon config` / `nebulon config <key> <value>`
+
+### Contract commands (examples)
+
+```bash
+nebulon contract list
+nebulon contract <id> details
+nebulon contract <id> add term payment 20
+nebulon contract <id> add term deadline 8d
+nebulon contract <id> add milestone "Draft spec"
+nebulon contract <id> sign
+nebulon contract <id> fund
+nebulon contract <id> milestone 1 ready
+nebulon contract <id> milestone 1 confirm
+nebulon contract <id> claim_funds
+```
+
+### Verbose diagnostics
+
+Use `--verbose` on contract commands to show additional progress and routing
+details:
+
+```bash
+nebulon contract <id> fund --verbose
 ```
 
-Notes:
-- This package is private for now. Do not publish to npm until you are ready.
-- Config and wallets are stored under `~/.nebulon/`.
+## Configuration and storage
+
+By default, configuration and wallets are stored under:
+
+- Windows: `%USERPROFILE%\\.nebulon\\`
+- macOS/Linux: `~/.nebulon/`
+
+Capsules live under `~/.nebulon/capsules/`. You can override the base directory
+with the `NEBULON_HOME` environment variable.
+
+Wallet import and export:
+
+- Import expects keypair files in `C:\\Nebulon\\Wallets` (Windows).
+- Export writes the active wallet to `C:\\Nebulon\\Wallets`.
+
+## Version
+
+```bash
+nebulon --version
+nebulon -v
+```
+
+## Troubleshooting
+
+- If `login` or hosted actions fail, re-run `nebulon config` and confirm backend
+  URLs and network settings.
+- If RPC calls fail, verify the configured `rpcUrl` and `wsUrl`.
+- Use `nebulon contract ... --verbose` for detailed progress output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nebulon-escrow-cli",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Nebulon CLI",
   "author": "northbyt3 <northbyt3@gmail.com>",
   "license": "UNLICENSED",

package/src/commands/contract.js

@@ -165,6 +165,9 @@ const getEphemeralProgram = async (config, signerKeypair, options = {}) => {
 const getDelegationValidator = async (config) => {
   const endpoint = (config.ephemeralProviderUrl || "").toLowerCase();
   const wsEndpoint = (config.ephemeralWsUrl || "").toLowerCase();
+  if (config && config.__verbose) {
+    console.log("DEBUG: delegation resolver endpoints", { endpoint, wsEndpoint });
+  }
   if (endpoint.includes("localhost") || endpoint.includes("127.0.0.1")) {
     return LOCAL_VALIDATOR_IDENTITY;
   }
@@ -185,6 +188,9 @@ const getDelegationValidator = async (config) => {
   if (shouldUseRouter && config.ephemeralProviderUrl) {
     const cacheKey = `${endpoint}|${wsEndpoint}`;
     if (cachedValidator && cachedValidatorEndpoint === cacheKey) {
+      if (config && config.__verbose) {
+        console.log("DEBUG: using cached validator", cachedValidator.toBase58());
+      }
       return cachedValidator;
     }
     try {
@@ -193,7 +199,7 @@ const getDelegationValidator = async (config) => {
       });
       const closest = await router.getClosestValidator();
       if (config && config.__verbose) {
-        console.log("Router closest:", JSON.stringify(closest));
+        console.log("DEBUG: router closest validator:", closest);
       }
       const identity =
         closest?.validatorIdentity || closest?.identity || closest?.validator;
@@ -209,8 +215,14 @@ const getDelegationValidator = async (config) => {
   }
   const fallback = safePublicKey(config.ephemeralValidatorIdentity);
   if (fallback) {
+    if (config && config.__verbose) {
+      console.log("DEBUG: using configured validator identity", fallback.toBase58());
+    }
     return fallback;
   }
+  if (config && config.__verbose) {
+    console.warn("DEBUG: no validator identity resolved.");
+  }
   return null;
 };
 
@@ -1067,6 +1079,13 @@ const ensureDelegatedAccount = async (
   options
 ) => {
   const info = await program.provider.connection.getAccountInfo(pda, "confirmed");
+  if (isVerbose(options)) {
+    console.log("DEBUG: delegation check", {
+      pda: pda.toBase58(),
+      owner: info?.owner?.toBase58?.(),
+      delegated: Boolean(info && info.owner.equals(DELEGATION_PROGRAM_ID)),
+    });
+  }
   if (info && info.owner.equals(DELEGATION_PROGRAM_ID)) {
     if (isVerbose(options)) {
       console.log(`Delegation already active for ${pda.toBase58()}; skipping.`);
@@ -1124,6 +1143,13 @@ const ensureDelegatedEscrow = async (
     escrowPda,
     "confirmed"
   );
+  if (isVerbose(options)) {
+    console.log("DEBUG: escrow delegation check", {
+      escrow: escrowPda.toBase58(),
+      owner: info?.owner?.toBase58?.(),
+      delegated: Boolean(info && info.owner.equals(DELEGATION_PROGRAM_ID)),
+    });
+  }
   if (info && info.owner.equals(DELEGATION_PROGRAM_ID)) {
     if (isVerbose(options)) {
       console.log(`Delegation already active for ${escrowPda.toBase58()}; skipping.`);
@@ -2210,6 +2236,27 @@ const runSignContract = async (config, contract, options) => {
   }
 
   console.log("Processing.");
+  if (isVerbose(options)) {
+    console.log("DEBUG: PER config", {
+      ephemeralProviderUrl: config.ephemeralProviderUrl,
+      ephemeralWsUrl: config.ephemeralWsUrl,
+      ephemeralValidatorIdentity: config.ephemeralValidatorIdentity,
+      rpcUrl: config.rpcUrl,
+      wsUrl: config.wsUrl,
+      network: config.network,
+    });
+    try {
+      if (config.ephemeralProviderUrl) {
+        const router = new ConnectionMagicRouter(config.ephemeralProviderUrl, {
+          wsEndpoint: config.ephemeralWsUrl || undefined,
+        });
+        const closest = await router.getClosestValidator();
+        console.log("DEBUG: router closest validator (sign flow):", closest);
+      }
+    } catch (error) {
+      console.log("DEBUG: router closest validator lookup failed:", error?.message || error);
+    }
+  }
   logProgress("Submitting signature on ER");
   let signSig = null;
   let commitSig = null;
@@ -2228,17 +2275,26 @@ const runSignContract = async (config, contract, options) => {
       programId,
       program.provider
     );
-  signSig = await erProgram.methods
-    .signPrivateTerms(new anchor.BN(escrowId.toString()))
-    .accounts({
-      user: keypair.publicKey,
-      payer: sessionSigner.publicKey,
-      sessionToken: sessionPda,
-      escrow: escrowPda,
-      terms: termsPda,
-    })
-    .signers([sessionSigner])
-    .rpc({ skipPreflight: true });
+  try {
+    signSig = await erProgram.methods
+      .signPrivateTerms(new anchor.BN(escrowId.toString()))
+      .accounts({
+        user: keypair.publicKey,
+        payer: sessionSigner.publicKey,
+        sessionToken: sessionPda,
+        escrow: escrowPda,
+        terms: termsPda,
+      })
+      .signers([sessionSigner])
+      .rpc({ skipPreflight: true });
+  } catch (error) {
+    console.error("ERROR: signPrivateTerms failed:", error?.message || error);
+    const msg = (error?.message || "").toLowerCase();
+    if (msg.includes("invalidwritableaccount")) {
+      console.error("HINT: InvalidWritableAccount usually means validator mismatch. Run with --verbose and compare router validator vs delegation.");
+    }
+    throw error;
+  }
   logTx("Signature submitted.", signSig, true);
   try {
     logProgress("Committing terms on ER");

package/src/commands/init.js

@@ -140,21 +140,15 @@ const runInit = async (options = {}, capsuleName) => {
     let backendAnswer = { backendUrl: config.backendUrl };
     let backendSource = config.backendSource || "custom";
     let backendNetwork = null;
-    let serverChoice = null;
-    try {
-      await getConfig((config.backendUrl || "http://174.138.42.117:3333").trim());
-      serverChoice = await prompt({
-        type: "select",
-        name: "server",
-        message: "Use official server or custom?",
-        choices: [
-          { name: "official", message: "Official server" },
-          { name: "custom", message: "Custom server" },
-        ],
-      });
-    } catch (error) {
-      serverChoice = { server: "custom" };
-    }
+    const serverChoice = await prompt({
+      type: "select",
+      name: "server",
+      message: "Use official server or custom?",
+      choices: [
+        { name: "official", message: "Official server" },
+        { name: "custom", message: "Custom server" },
+      ],
+    });
 
     if (serverChoice.server === "custom") {
       backendAnswer = await prompt({

package/src/constants.js

@@ -26,7 +26,7 @@ const DEFAULT_CONFIG = {
   rpcUrl: NETWORK_PRESETS.localnet.rpcUrl,
   wsUrl: NETWORK_PRESETS.localnet.wsUrl,
   programId: PROGRAM_ID_DEFAULT,
-  backendUrl: "http://localhost:3333",
+  backendUrl: "http://174.138.42.117:3333",
   usdcMint: NETWORK_PRESETS.localnet.usdcMint,
   programIdSource: "custom",
   usdcMintSource: "custom",