@jinn-network/client 0.1.0 → 0.1.1-canary.4a6ed8b2

package/README.md

@@ -16,20 +16,49 @@ yarn global add @jinn-network/client@latest
 
 ## Quick start
 
+The fast path for a new operator on Base Sepolia:
+
+```bash
+# Zero-to-running in one command (init + funding check + bootstrap + run).
+JINN_PASSWORD=your-keystore-password jinn quickstart
+```
+
+Or step by step:
+
 ```bash
-# Generate wallet and keystore
-jinn init
+# 1. Generate the encrypted keystore (picks an HD wallet deterministically).
+JINN_PASSWORD=your-keystore-password jinn init
 
-# Check environment readiness
-jinn doctor
+# 2. Verify the environment and resolved deployment.
+jinn doctor --human
 
-# Start the daemon
+# 3. List exact funding gaps. On testnet this is ETH only — the staking pool
+#    is managed protocol-side and operators don't hold bond tokens directly.
+jinn fund-requirements --human
+
+# 4. Send the requested testnet funds to the printed master address, then:
+JINN_PASSWORD=your-keystore-password jinn bootstrap
+
+# 5. Start the daemon.
 JINN_PASSWORD=your-keystore-password jinn run
 ```
 
-On first run, the bootstrap generates a master wallet and prints a funding address. Send testnet ETH to it, then re-run. The bootstrap is idempotent — it picks up where it left off.
+`jinn init`, `jinn fund-requirements`, `jinn bootstrap`, and `jinn run` all
+share the same encrypted keystore and fleet state under `~/.jinn-client/earning/`
+by default. They are idempotent — re-run any of them safely.
 
-`JINN_PASSWORD` encrypts the local keystore and is env-only; never put it in a config file.
+To keep testnet and mainnet state side-by-side on the same machine, set
+`JINN_EARNING_DIR` to a network-specific path:
+
+```bash
+JINN_NETWORK=testnet JINN_EARNING_DIR=~/.jinn-client/earning-testnet jinn run
+JINN_NETWORK=mainnet JINN_EARNING_DIR=~/.jinn-client/earning-mainnet jinn run
+```
+
+`JINN_PASSWORD` encrypts the local keystore and is **required** for every
+verb that touches private keys (`init`, `bootstrap`, `run`,
+`fund-requirements`, `keys backup`, `submit-intent`, `claim-rewards`,
+`withdraw`). It is env-only; never put it in a config file.
 
 ## Try without installing
 
@@ -57,6 +86,8 @@ Because the macOS keychain securely encrypts OAuth tokens, you **cannot** simply
    Use `-it` so the CLI can open a browser (or show a URL to visit) and receive input. The process stays in the foreground until you finish sign-in.
    *Follow the URL to authenticate in your browser.*
 
+   > **Note:** this block assumes you've cloned the git repo — the compose file lives at `client/docker-compose.yml`. If you installed via `npm install -g`, copy the compose file from `$(npm root -g)/@jinn-network/client/docker-compose.yml` to a working directory first, then run the commands there.
+
 3. **Start the Fleet:** Now that the Docker volume holds the token, start the headless daemon:
    ```bash
    docker compose up -d
@@ -74,13 +105,16 @@ docker run --rm ghcr.io/jinn-network/client:latest version --json
 
 | Command | Purpose | Idempotent |
 |---|---|---|
-| `jinn init` | Generate wallet + keystore | Yes |
+| `jinn quickstart` | One-shot init + funding check + bootstrap + run | Yes |
+| `jinn init` | Generate wallet + keystore + fleet state | Yes |
 | `jinn doctor` | Preflight checks without mutation | Yes |
 | `jinn bootstrap` | Advance toward a running fleet | Yes |
 | `jinn fund-requirements` | List what needs funding | Yes |
 | `jinn run` | Start the daemon (foreground) | N/A |
 | `jinn stop` | Signal a running daemon to stop | Yes |
 | `jinn version` | Version, phase, deployment digest | Yes |
+| `jinn update` | Update the client package + refresh plugins | Yes |
+| `jinn plugin install` | Wire Jinn into Claude Code / Codex / other AI tools | Yes |
 
 ### Monitoring
 
@@ -104,7 +138,8 @@ All action verbs support `--dry-run` and `--yes`.
 | `jinn fleet scale --to N` | Grow or shrink fleet |
 | `jinn fleet retire <index>` | Retire one service |
 | `jinn withdraw --to <addr>` | Sweep wallets to external address |
-| `jinn keys backup --output <path>` | Export mnemonic |
+| `jinn keys backup --output <path>` | Export mnemonic (writes plaintext; treat the output file as seed material) |
+| `jinn keys change-password` | Re-encrypt the keystore with a new password |
 
 ## Output contract
 
@@ -126,7 +161,7 @@ JINN_PASSWORD=secret jinn run --config ./my-config.json
 
 | Config key | Env override | Default |
 |---|---|---|
-| network | JINN_NETWORK | testnet (flips to mainnet at launch) |
+| network | JINN_NETWORK | read from config; `mainnet` if unset (flips to `testnet` default for the Phase 2 mainnet launch window) |
 | rpcUrl | BASE_RPC_URL / JINN_RPC_URL | network-appropriate public RPC |
 | claudeModel | JINN_CLAUDE_MODEL | claude-haiku-4-5-20251001 |
 | claudePath | JINN_CLAUDE_PATH | claude |
@@ -139,14 +174,66 @@ JINN_PASSWORD=secret jinn run --config ./my-config.json
 
 `JINN_PASSWORD` is env-only (keystore encryption, never in config files). Alternatively, use `--password-fd <N>` to read from a file descriptor.
 
+## Tokens
+
+| Role | Phase 1b (testnet, Base Sepolia) | Phase 2 (mainnet, Base) |
+|---|---|---|
+| Gas (native) | ETH (CDP auto-funded on testnet) | ETH |
+| Staking bond | Pooled, protocol-managed via stOLAS distributor (operators hold nothing) | OLAS (operator-held) |
+| Reward | stOLAS | OLAS (+ JINN incentives after launch) |
+
+**Important:** under stOLAS standard mode (the Phase 1b default), operators
+**do not hold a bond token themselves**. The stOLAS distributor pools JINN
+contributed by stakers and stakes on behalf of operators; your service gets
+created against that shared pool. `jinn fund-requirements` surfaces only the
+per-wallet ETH you need. If the distributor pool is drained, `jinn doctor`
+will warn you — the fix is a protocol-team refill, not operator action.
+
 ## Switching to mainnet
 
 When Phase 2 launches, the default flips. Until then:
 
 ```bash
-JINN_NETWORK=mainnet JINN_PASSWORD=secret jinn run
+JINN_NETWORK=mainnet \
+JINN_EARNING_DIR=~/.jinn-client/earning-mainnet \
+JINN_PASSWORD=secret \
+jinn run
 ```
 
+Use a distinct `JINN_EARNING_DIR` to keep testnet and mainnet keystore
+state isolated. Mixing them on the same directory is an easy way to
+point a mainnet daemon at a testnet-derived master wallet.
+
+## Troubleshooting
+
+Quick answers to the things that typically surprise new operators:
+
+- **Bootstrap loops for a minute then exits with `funding_required`** —
+  the CDP faucet drip is small (~0.0001 ETH per call) and the bootstrap
+  floor is 0.005 ETH. The client now drains the faucet up to 60 times per
+  invocation automatically; if you still see `funding_required`, CDP rate-
+  limited your master address. Wait 24h or fund manually:
+  <https://portal.cdp.coinbase.com/products/faucet>.
+- **Claude session exits in ~18 seconds with no trades** — usually means
+  the daemon ran from source (via `tsx`) instead of the compiled `dist/`,
+  so the MCP wrapper couldn't load `mcp-tools.js`. Run `yarn build && yarn
+  dev` (dev) or reinstall via `npm install -g @jinn-network/client@latest`
+  (operator). `jinn doctor` flags this as `daemon_runtime_ready`.
+- **Bootstrap fails with `Overflow(20, 0)` at `distributor.stake()`** —
+  the testnet stOLAS distributor pool is drained. Operators cannot fix
+  this; the Jinn protocol team has to refill it. Report to the testnet
+  status channel and re-run `jinn bootstrap` once the pool is topped up.
+- **Position auto-closed within seconds of opening** — most likely
+  a competing trading bot is active on the same Hyperliquid master. Use a
+  fresh HL master per protocol test; do not share master accounts between
+  experiments.
+- **`jinn doctor` passes but `jinn run` fails** — check the specific
+  check names in doctor's output vs the specific error from `run`. The
+  most common mismatch is auth-context: if you're in the `client/` git
+  checkout dir, `detectAuthContext` infers `docker-compose` mode even on
+  a bare host. Run the daemon from `$HOME` or any directory without a
+  `docker-compose.yml` that names `jinn-daemon`.
+
 ## How it works
 
 The daemon runs three concurrent loops:

package/deployments/deployment-jinn-testnet-faucet-baseSepolia-fast.json

@@ -0,0 +1,15 @@
+{
+  "network": "baseSepolia",
+  "chainId": 84532,
+  "deployer": "0x15e78734481bD31F6e183dad05225505a45ACd07",
+  "deployedAt": "2026-04-20T13:14:18.413Z",
+  "config": {
+    "jinnToken": "0xAB9a01cd4A379e36006ec6df2960CF39EF79df63",
+    "dripAmount": "100000000000000000000",
+    "dripInterval": 86400,
+    "initialSupplyBridged": "1000000000000000000000"
+  },
+  "contracts": {
+    "faucet": "0xa7c2DBA07E41F16eF94cbEAeAEd97bC904032619"
+  }
+}

package/dist/adapters/claim-registry/abi.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Typed ABI fragments for ClaimRegistry.
+ *
+ * Mirrors the Solidity interface in contracts/src/claiming/ClaimRegistry.sol.
+ * Use these instead of the inline fragment in adapters/mech/types.ts when
+ * constructing a ClaimRegistryClient — they include the full event set.
+ */
+export declare const CLAIM_REGISTRY_ABI: readonly [{
+    readonly name: "claimJob";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "requestId";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "releaseClaim";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "requestId";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "expireClaim";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "requestId";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "getJobClaim";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "requestId";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "claimer";
+        readonly type: "address";
+    }, {
+        readonly name: "expiresAt";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "claims";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "claimer";
+        readonly type: "address";
+    }, {
+        readonly name: "expiresAt";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "claimTTL";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "expiredClaimCount";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "JobClaimed";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "requestId";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "claimer";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "expiresAt";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly name: "ClaimExpired";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "requestId";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "previousClaimer";
+        readonly type: "address";
+        readonly indexed: true;
+    }];
+}, {
+    readonly name: "ClaimReleased";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "requestId";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "claimer";
+        readonly type: "address";
+        readonly indexed: true;
+    }];
+}];
+export type ClaimRegistryAbi = typeof CLAIM_REGISTRY_ABI;

package/dist/adapters/claim-registry/abi.js

@@ -0,0 +1,93 @@
+/**
+ * Typed ABI fragments for ClaimRegistry.
+ *
+ * Mirrors the Solidity interface in contracts/src/claiming/ClaimRegistry.sol.
+ * Use these instead of the inline fragment in adapters/mech/types.ts when
+ * constructing a ClaimRegistryClient — they include the full event set.
+ */
+export const CLAIM_REGISTRY_ABI = [
+    // ── Write functions ──────────────────────────────────────────────────────────
+    {
+        name: 'claimJob',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [{ name: 'requestId', type: 'bytes32' }],
+        outputs: [],
+    },
+    {
+        name: 'releaseClaim',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [{ name: 'requestId', type: 'bytes32' }],
+        outputs: [],
+    },
+    {
+        name: 'expireClaim',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [{ name: 'requestId', type: 'bytes32' }],
+        outputs: [],
+    },
+    // ── Read functions ───────────────────────────────────────────────────────────
+    {
+        name: 'getJobClaim',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: 'requestId', type: 'bytes32' }],
+        outputs: [
+            { name: 'claimer', type: 'address' },
+            { name: 'expiresAt', type: 'uint256' },
+        ],
+    },
+    {
+        name: 'claims',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: '', type: 'bytes32' }],
+        outputs: [
+            { name: 'claimer', type: 'address' },
+            { name: 'expiresAt', type: 'uint256' },
+        ],
+    },
+    {
+        name: 'claimTTL',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ name: '', type: 'uint256' }],
+    },
+    {
+        name: 'expiredClaimCount',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: '', type: 'address' }],
+        outputs: [{ name: '', type: 'uint256' }],
+    },
+    // ── Events ───────────────────────────────────────────────────────────────────
+    {
+        name: 'JobClaimed',
+        type: 'event',
+        inputs: [
+            { name: 'requestId', type: 'bytes32', indexed: true },
+            { name: 'claimer', type: 'address', indexed: true },
+            { name: 'expiresAt', type: 'uint256', indexed: false },
+        ],
+    },
+    {
+        name: 'ClaimExpired',
+        type: 'event',
+        inputs: [
+            { name: 'requestId', type: 'bytes32', indexed: true },
+            { name: 'previousClaimer', type: 'address', indexed: true },
+        ],
+    },
+    {
+        name: 'ClaimReleased',
+        type: 'event',
+        inputs: [
+            { name: 'requestId', type: 'bytes32', indexed: true },
+            { name: 'claimer', type: 'address', indexed: true },
+        ],
+    },
+];
+//# sourceMappingURL=abi.js.map

package/dist/adapters/claim-registry/abi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.js","sourceRoot":"","sources":["../../../src/adapters/claim-registry/abi.ts"],"names":[],"mappings":"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"}

package/dist/adapters/claim-registry/client.d.ts

@@ -0,0 +1,89 @@
+/**
+ * ClaimRegistryClient — typed wrapper for the ClaimRegistry contract.
+ *
+ * Wraps the read/write surfaces of ClaimRegistry with proper types and
+ * idiomatic async interfaces.
+ *
+ * Write operations (claimJob, releaseClaim) go through the Safe multisig via
+ * executeSafeTransaction. This is required so that the on-chain claimer address
+ * matches the Safe — our canonical OLAS/staking identity. Using the raw EOA
+ * would cause a mismatch: OnChainClaimPolicy already claims through the Safe,
+ * so `weAlreadyClaimed()` would return false even when the Safe holds the claim,
+ * triggering a redundant on-chain write that reverts as JobAlreadyClaimed.
+ *
+ * expireClaim() is permissionless (anyone can GC others' expired claims) and
+ * is kept as a direct EOA call — the gas payer does not affect claim ownership.
+ */
+import { type Address, type Hex, type PublicClient, type WalletClient } from 'viem';
+export declare const ZERO_ADDRESS: Address;
+export interface JobClaimInfo {
+    claimer: Address;
+    /** Unix timestamp (seconds) when the claim expires. 0 if no active claim. */
+    expiresAt: bigint;
+    /** True if claimer !== ZERO_ADDRESS and expiresAt > 0 (claim is still active per contract). */
+    isActive: boolean;
+}
+export interface ClaimJobResult {
+    /** Transaction hash. Empty string when skipped (already ours or failed). */
+    txHash: string;
+    /** True if we now hold the claim (new or pre-existing). */
+    claimed: boolean;
+}
+export declare class ClaimRegistryClient {
+    private readonly publicClient;
+    private readonly walletClient;
+    private readonly contractAddress;
+    /**
+     * The Safe multisig address — used as the canonical claimer identity.
+     * claimJob/releaseClaim are routed through Safe so that msg.sender on-chain
+     * is the Safe address, matching the OLAS staking identity.
+     */
+    private readonly safeAddress;
+    constructor(publicClient: PublicClient, walletClient: WalletClient, contractAddress: Address, 
+    /**
+     * The Safe multisig address — used as the canonical claimer identity.
+     * claimJob/releaseClaim are routed through Safe so that msg.sender on-chain
+     * is the Safe address, matching the OLAS staking identity.
+     */
+    safeAddress: Address);
+    /**
+     * Read the active claim for a request.
+     * Returns `(ZERO_ADDRESS, 0, false)` if no active claim (contract returns
+     * (address(0), 0) for expired/non-existent claims).
+     */
+    getJobClaim(requestId: Hex): Promise<JobClaimInfo>;
+    /**
+     * Check whether the Safe already holds an active claim for this request.
+     * Used for idempotency on resume.
+     */
+    weAlreadyClaimed(requestId: Hex): Promise<boolean>;
+    /**
+     * Claim a marketplace request through the Safe multisig.
+     *
+     * Idempotent: if the Safe already holds an active claim, returns
+     * `{ txHash: '', claimed: true }` without submitting a transaction.
+     *
+     * Returns `{ txHash: '', claimed: false }` when:
+     *   - Another address holds an active claim
+     *   - The eligibility check fails (IneligibleToClaim)
+     *   - The tx reverts for any other handled reason
+     *
+     * Throws on unrecognised RPC errors.
+     */
+    claimJob(requestId: Hex): Promise<ClaimJobResult>;
+    /**
+     * Voluntarily release a claim through the Safe multisig (no punishment).
+     * Should only be called when the Safe holds the claim.
+     * No-op (returns false) if the Safe doesn't hold the claim.
+     */
+    releaseClaim(requestId: Hex): Promise<boolean>;
+    /**
+     * Garbage-collect a stale (expired) claim.
+     *
+     * expireClaim is permissionless — anyone can call it to GC others' expired
+     * claims. The caller gets no reward; the previous claimer gets an
+     * expiredClaimCount increment. Since the gas payer doesn't affect claim
+     * ownership, this is sent directly from the EOA (cheaper than a Safe tx).
+     */
+    expireClaim(requestId: Hex): Promise<boolean>;
+}