Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
1ab87be
subsidy provider support
alexcos20 Oct 1, 2026
56be45c
fix comments
alexcos20 Oct 1, 2026
266e449
format
alexcos20 Oct 1, 2026
ef96af4
escrow v2
alexcos20 Oct 8, 2026
36406d9
use custom contracts and node
alexcos20 Oct 8, 2026
0d1399c
fix test
alexcos20 Oct 8, 2026
d45b938
fix CLAUDE.md
alexcos20 Oct 8, 2026
89b5ac5
fix lock
alexcos20 Oct 8, 2026
2df41be
bump to lib@9.3.0-next.4
alexcos20 Oct 13, 2026
2020fb0
Merge branch 'main' into feature/subsidy_provider
alexcos20 Oct 19, 2026
e02a5c8
use latest contracts in ci
alexcos20 Oct 19, 2026
0356539
fix ISO date guard
alexcos20 Oct 19, 2026
f8d7e00
updates to lib v10
alexcos20 Nov 11, 2026
af64001
Merge branch 'main' into feature/subsidy_provider
alexcos20 Nov 11, 2026
5ad4dc1
Merge branch 'main' into feature/subsidy_provider
alexcos20 Nov 11, 2026
daec4b9
fixes
alexcos20 Nov 11, 2026
2c10765
relax positional params + enforce guards
alexcos20 Nov 11, 2026
bc4d883
remove custom node and contracts from ci
alexcos20 Nov 11, 2026
51907e0
update CLAUDE.md to use node24
alexcos20 Nov 11, 2026
458e402
update and fix tests
alexcos20 Nov 11, 2026
292e80f
always show subsidy percent
alexcos20 Nov 11, 2026
2555ae9
fix message about subsidy support
alexcos20 Nov 11, 2026
692127f
Use colors for better subsidy visibility
alexcos20 Nov 11, 2026
6fa631c
remove duplicate token enable
alexcos20 Nov 11, 2026
0cda5e8
Fund only the payer's share when a prepaid subsidy covers the job
alexcos20 Nov 16, 2026
fb66252
Let getSubsidyStatus --subsidy query providers the node does not adve…
alexcos20 Nov 16, 2026
732ef2e
fix review comments
alexcos20 Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,7 @@ jobs:
bash -x start_ocean.sh --with-typesense 2>&1 > start_ocean.log &
- name: Install dependencies
run: npm ci
- run: npm run build
- run: docker image ls
- name: Wait for node to be ready
run: |
Expand Down
13 changes: 7 additions & 6 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

`ocean-cli` (npm package `@oceanprotocol/cli`, version 2.0.0; installs a `bin` named `ocean-cli`) is a TypeScript CLI that wraps the Ocean Protocol JavaScript library (`@oceanprotocol/lib`, a.k.a. ocean.js) to publish, edit, consume/download, and run compute-to-data (C2D) on assets, plus manage escrow payments, access lists, persistent-storage buckets, auth tokens, and admin node logs. It talks to an **Ocean Node** (the single service that replaced the old standalone Provider and Aquarius apps — it does metadata caching, indexing, encryption, ordering, and compute) and to an EVM chain via an RPC endpoint.

The package is pure ESM (`"type": "module"` in `package.json`). All relative imports MUST carry an explicit `.js` extension even though the source is `.ts` (e.g. `import { Commands } from "./commands.js"`). Node 22 is expected (`.nvmrc` = `22.23.1`; CI pins the same). The dev toolchain sets the floor: `eslint@10` needs `>=22.13.0` and `release-it@21` needs `>=22.21.0`, so an older 22.x will fail `npm run lint` / `npm run release` even though `engines.node` is only `>=22` (that bound is for consumers of the published package, who get `dependencies` only).
The package is pure ESM (`"type": "module"` in `package.json`). All relative imports MUST carry an explicit `.js` extension even though the source is `.ts` (e.g. `import { Commands } from "./commands.js"`). Node 24 is expected for local dev (`.nvmrc` = `24`). CI runs the build, lint, and system-test jobs on a matrix of Node `22`, `24`, and `26` (with several steps pinned to `24`), while `publish.yml` pins `22.23.1`. The dev toolchain sets the floor: `eslint@10` needs `>=22.13.0` and `release-it@21` needs `>=22.21.0`, so a Node older than those will fail `npm run lint` / `npm run release` even though `engines.node` is only `>=22` (that bound is for consumers of the published package, who get `dependencies` only).

## Commands

Expand Down Expand Up @@ -78,8 +78,9 @@ All registered in `src/cli.ts` via Commander (`commander` v13). Every command su
- Assets: `getDDO`, `publish`, `publishAlgo`, `editAsset` (alias `edit`), `download`, `allowAlgo`.
- Compute: `startCompute`, `startFreeCompute`, `getComputeEnvironments` (alias `getC2DEnvs`), `computeStreamableLogs`, `stopCompute`, `getJobStatus`, `downloadJobResults`.
- Tokens/auth: `mintOcean`, `generateAuthToken`, `invalidateAuthToken`.
- Escrow: `depositEscrow`, `getUserFundsEscrow`, `withdrawFromEscrow`, `authorizeEscrow`, `getAuthorizationsEscrow`.
- Escrow: `depositEscrow`, `getUserFundsEscrow`, `withdrawFromEscrow`, `authorizeEscrow`, `getAuthorizationsEscrow`, `getEscrowInfo` (alias `escrowInfo`).
- Access lists: `createAccessList`, `addToAccessList`, `checkAccessList`, `removeFromAccessList`.
- Subsidy providers: `getSubsidyProviders` (alias `subsidyProviders`), `getSubsidyStatus` (alias `subsidyStatus`). Provider addresses come **only** from the node's status (`nodeSubsidyInfo` in `nodeConnection.ts`), never from bundled config — a node may not support subsidies. `getSubsidyStatus` uses the ocean.js `SubsidyView`/`OPFSubsidyProvider`/`OneTimeSubsidyProvider` wrappers. Compute/service commands (`startCompute`, `startService`, `extendService`) also take `--subsidyProviders <list>` (tri-state: omit → node default, `none`/empty → `[]`, CSV → those; parsed by `parseSubsidyProviders` in `helpers.ts`). `startFreeCompute` ignores it.
- Persistent storage buckets: `createBucket`, `addFileToBucket`, `listBuckets`, `listFilesInBucket`, `getFileObject`, `deleteFile`.
- Admin: `downloadNodeLogs`.
- Node selection: `setNode` (alias `useNode`), `getNode` (alias `currentNode`).
Expand Down Expand Up @@ -158,7 +159,7 @@ uses directly. `destroyProviders()` tears providers down on exit (next to `stopP
- `createAssetUtil(...)` wraps ocean.js `createAsset` (used by publish/publishAlgo and the interactive publisher). It resolves the active ERC20 template (`calculateActiveTemplateIndex` reads and `JSON.parse`s the `@oceanprotocol/contracts` `ERC20Template.json` ABI, resolved via `createRequire`/`require.resolve` so it works from any cwd — e.g. a global install — not a cwd-relative `node_modules` path), and for **Oasis Sapphire** (`config.sdk === 'oasis'`) wraps the signer with `wrapEthersSigner` from `@oasisprotocol/sapphire-ethers-v6` (`getSignerAccordingSdk`; sapphire-paratime v2 moved its ethers integration into that package, and it throws `SignerHasNoProviderError` for a provider-less signer) and deploys an allow access list before creating the asset.
- `updateAssetMetadata(...)` — used by `editAsset`, `allowAlgo`, `disallowAlgo` and the interactive publisher. It validates the DDO via `aquarius.validate`, then either `ProviderInstance.encrypt`s the DDO (flags = 2) or hexlifies raw JSON (flags = 0) depending on the `encryptDDO` flag, then calls `nft.setMetadata`.
- `handleComputeOrder(...)` — the ordering state machine used in compute: validOrder + no fees → reuse as-is; validOrder + fees → `datatoken.reuseOrder` paying only provider fees; no order → `orderAsset` (pay 1 datatoken + fees). Approves provider-fee tokens first when the fee amount > 0.
- `resolveComputeInputs(...)` + `parseComputeInput(...)` — parse the datasets/algo CLI strings (DID | JSON object | array | mixed | legacy `[did:a,did:b]`), resolve DID entries through `aquarius.waitForIndexer`, pass raw `fileObject` entries through (aligned with a `null` DDO slot), and pick `providerURI` from the first DID-based DDO's `serviceEndpoint` (else fall back to `NODE_URL`).
- `resolveComputeInputs(...)` + `parseComputeInput(...)` — parse the datasets/algo CLI strings (DID | JSON object | array | mixed | legacy `[did:a,did:b]`), resolve DID entries through `aquarius.waitForIndexer`, pass raw entries through (a `fileObject`, or for an algorithm inline `meta.rawcode`; aligned with a `null` DDO slot), and pick `providerURI` from the first DID-based DDO's `serviceEndpoint` (else fall back to `NODE_URL`).
- `fixAndParseProviderFees(...)` — regex-based repair of the stringified provider-initialize response that is round-tripped from `initializeCompute` into `computeStart` (adds quotes to keys, DIDs, hex addresses). Fragile by design; touch carefully.
- `getIndexingWaitSettings()` — reads the `INDEXING_*` env vars.
- Signing/encryption is always done via the `Signer` and `ProviderInstance` from ocean.js; the CLI never handles raw keys beyond constructing the `ethers.Wallet`.
Expand All @@ -175,16 +176,16 @@ uses directly. `destroyProviders()` tears providers down on exit (next to `stopP
The `startCompute` **action in `cli.ts`** orchestrates a two-phase flow (not a single `Commands` method). It first resolves the **payment/escrow chain** with `resolveChainId(options.chainId)` (`--chainId` flag → default chain → error) and passes it as an explicit trailing param to both compute methods:

1. `commands.initializeCompute([...], paymentChainId)` — resolves inputs, fetches compute envs (`ProviderInstance.getComputeEnvironments`), matches the env by id, validates that the **payment chain** is in both `computeEnv.fees` and the RPC registry, plus paymentToken/resources/maxJobDuration (capping to `env.maxJobDuration`), and returns the provider `initializeCompute` response (payment + provider fees). Signs against the payment chain (`signerFor(paymentChainId)`).
2. Prints payment details, converts amount with `unitsToAmount`, and asks for confirmation unless `--accept true` (hard error on non-TTY).
3. `commands.computeStart([...], paymentChainId)` — **per-asset ordering**: each DID-based dataset/algorithm DDO is ordered on **its own** chain via a per-chain `{ signer, config, Datatoken }` context (`orderCtxFor(ddo.chainId)`, memoized within the call), replacing the old single `Datatoken` on the signer's one chain. Escrow funds (`EscrowContract.verifyFundsForEscrowPayment`), deposit/authorize, and `ProviderInstance.computeStart` all run on the **payment chain** (`paymentSigner` = `signerFor(paymentChainId)`), independent of where the assets live (C2D V2: all datasets passed together in `assets`; the old `additionalDatasets` param is unused). Prints `JobID` and the agreement id (`payment.lockTx`).
2. Prints payment details, converts amount with `unitsToAmount`, quotes the prepaid subsidy with `commands.computePrefundedUnits(subsidyProviders, lockUnits)` (it reuses the env/node/resources that `initializeCompute` stored in `computeQuoteCtx`), prints `total job cost` / `prepaid subsidy covers` / `you pay`, and asks for confirmation unless `--accept true` (hard error on non-TTY). The quoted figure is passed to `computeStart` as its 4th param so the confirmed share is the funded share.
3. `commands.computeStart([...], paymentChainId)` — **per-asset ordering**: each DID-based dataset/algorithm DDO is ordered on **its own** chain via a per-chain `{ signer, config, Datatoken }` context (`orderCtxFor(ddo.chainId)`, memoized within the call), replacing the old single `Datatoken` on the signer's one chain. Escrow funds (`EscrowContract.verifyFundsForEscrowPayment`), deposit/authorize, and `ProviderInstance.computeStart` all run on the **payment chain** (`paymentSigner` = `signerFor(paymentChainId)`), independent of where the assets live (C2D V2: all datasets passed together in `assets`; the old `additionalDatasets` param is unused). Prints `JobID` and the agreement id (`payment.lockTx`). **Prepaid subsidy:** before funding, `prefundedUnitsForJob` calls ocean.js `estimateJobSubsidy` (lib ≥ 10.1.0; node status + image gate + per-provider quotes) and the pure `prefundedLockUnits()` helper (`helpers.ts`) turns the result into the pre-funded base units for the `--subsidyProviders` tri-state (omitted → the node-set projection; a list → only the named providers, since the node *replaces* its set; `[]` → 0). Only the **payer share** (`lock − prefunded`) is passed to `verifyFundsForEscrowPayment` and to the balance/authorize follow-up, so a fully sponsored job deposits nothing; the lib call is still made with `"0"` because it also creates/repairs the authorization the node needs. Any estimate failure falls back to full payer funding. `startService`/`extendService` use the same method with `jobType` 2 (image gate predicate: a non-empty entrypoint or cmd), passed as a `quotePrefunded` callback into `quoteServicePayerShare` (`serviceHelpers.ts`, read-only). The order is quote → `confirmServicePayment` → `fundServiceEscrow`, so no deposit/authorize is sent before the user confirms; `fundServiceEscrow` passes **human** units for both lib amounts.

**Multi-chain compute (category d).** A single job may mix datasets/algorithm on different chains and pay/escrow on yet another. `--chainId` is **only** the payment chain; asset chains are always taken from each DDO, never passed by the user. `Commands.ensureComputeChainsRegistered(paymentChainId, ddos, algoDdo)` validates up front — via the pure `computeJobChainIds()` helper (`helpers.ts`) — that every chain the job touches (payment + each DID asset/algo chain) has a registered RPC, and errors listing the missing chain(s) before any paid order. In the common **single-chain** case every asset shares the payment chain, so ordering/escrow/`computeStart` are equivalent to before.

`startFreeCompute` → `freeComputeStart` calls `ProviderInstance.freeComputeStart` against a `free` env with no ordering/escrow; its `--chainId` just routes the signing chain (`routeExplicit`/`useChain`, like a category (c) command). `stopCompute`, `getJobStatus`, `downloadJobResults`, `computeStreamableLogs` are thin wrappers over the corresponding `ProviderInstance` methods. `getComputeEnvironments` additionally prints a per-env **payment summary** (fee chains + accepted tokens, via the pure `summarizeComputeEnvFees()` helper) so `--chainId`/`--paymentToken` are choosable without reading raw JSON.

### Escrow, access lists, persistent storage, auth, node logs

- **Escrow** (`EscrowContract` from ocean.js, address from `address.json`): `depositEscrow` approves then deposits; `withdrawFromEscrow` checks balance first; `authorizeEscrow` sets per-payee lock limits; `getUserFundsEscrow` / `getAuthorizationsEscrow` read state.
- **Escrow** (`EscrowContract` from ocean.js, address from `ConfigHelper` via `requireAddress(chainId, "escrow", …)`): `depositEscrow` approves then deposits; `withdrawFromEscrow` checks balance first; `authorizeEscrow` sets per-payee lock limits; `getUserFundsEscrow` / `getAuthorizationsEscrow` read state. **Escrow v2** (ocean.js escrow-v2 release / contracts `^3.2.0-rc.0`): `authorize` now **always overwrites** the on-chain record (it no longer no-ops when one exists — that is what makes renew/shorten/revoke reachable) and takes a trailing `expiryTimestamp` (unix seconds; `0` = indefinite, a past value revokes), surfaced as `authorizeEscrow --expiry`; `authorizeEscrowPayee` therefore dropped its old "already authorized → null tx" branch. `getAuthorizationsEscrow` prints the new 7th tuple field `expiryTimestamp`, and reads `Current Locked Amount` as **payer-funded only** (`P`); provider-sponsored tokens (`S`) live in a separate bucket. `getEscrowInfo [token]` is a read-only diagnostic: it reads `version`/`escrowKind`/`maxSponsorsPerLock` directly and feature-detects `isEscrowLockSubsidy`/`isEscrowEnterprise` via ERC-165 (`supportsInterface`), plus `getSponsoredTotal`/`getReclaimable` and the enterprise `feeCollector`/`isTokenAllowed` when a token is given; it degrades gracefully against a legacy escrow. The CLI never creates locks itself (the node does at compute/service start), so `createLock`/`reLock`'s new `jobType`/`subsidyProviders` params are only relevant through the node; `--subsidyProviders` on `startCompute`/`startService`/`extendService` is what feeds pre-funded sponsorship.
- **Access lists** (`AccesslistFactory` / `AccessListContract` from ocean.js): `createAccessList` deploys via the factory (address from `address.json`); membership is an ERC721 balance — `addToAccessList` mints/`batchMint`s NFTs, `checkAccessList` tests `balance > 0`, `removeFromAccessList` burns each token via `tokenOfOwnerByIndex`.
- **Persistent storage** (`ProviderInstance.*PersistentStorage*`): bucket CRUD + file upload/list/get/delete. `addFileToBucket` streams the file with a progress logger and a 30-minute (`UPLOAD_TIMEOUT_MS`) abort timeout; buckets can be gated by an access-list address.
- **Auth tokens**: `generateAuthToken` / `invalidateAuthToken` via `ProviderInstance`.
Expand Down
Loading
Loading