subsidy provider support

.github/workflows/ci.yml

@@ -141,6 +141,9 @@ jobs:
         working-directory: ${{ github.workspace }}/barge
         run: |
           bash -x start_ocean.sh --with-typesense 2>&1 > start_ocean.log &
+        env:
+          NODE_VERSION: pr-1479
+          CONTRACTS_VERSION: 3.2.0-rc.0
       - run: npm ci
       - run: npm run build
       - run: docker image ls

CLAUDE.md

@@ -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`).
@@ -184,7 +185,7 @@ The `startCompute` **action in `cli.ts`** orchestrates a two-phase flow (not a s
 
 ### 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`.

README.md

@@ -596,6 +596,17 @@ Notes:
 
 ---
 
+> **Escrow v2.** The escrow contracts now support **lock-time pre-funded sponsorship** (a subsidy
+> provider can back part or all of a lock when it is created, so a fully-sponsored user can transact
+> with no deposit) and **authorization expiry** (a payee key can be time-boxed or revoked). The CLI
+> reflects this: `authorizeEscrow` takes an `--expiry` and re-running it overwrites the record
+> (renew/shorten/revoke), `getAuthorizationsEscrow` prints the expiry, and `getEscrowInfo` reports
+> the escrow's capabilities and the sponsored bucket. Reading escrow state, note that
+> `getUserFunds().locked` and an authorization's `Current Locked Amount` now count only the payer's
+> **own** locked funds — provider-sponsored tokens live in a separate sponsored bucket
+> (`getEscrowInfo <token>`). These commands require the Escrow v2 deployment; they still work (and
+> degrade gracefully) against a legacy escrow. See the full change set in `PR_description.md`.
+
 **Deposit to Escrow:**
 
 - **Positional:**  
@@ -640,6 +651,20 @@ Notes:
   - `maxLockedAmount`: Maximum amount that can be locked by payee
   - `maxLockSeconds`: Maximum lock duration in seconds
   - `maxLockCounts`: Maximum number of locks allowed
+- Options:
+  - `-e, --expiry <timestamp>`: **(Escrow v2)** unix timestamp (seconds) after which the payee
+    can no longer create/extend locks. `0` = indefinite (default). Re-running `authorizeEscrow`
+    **overwrites** the existing authorization (renew/shorten); passing an `--expiry` in the past
+    **revokes** it. Claim and cancel are never gated by expiry, so existing locks stay claimable.
+
+  Examples — revoke a payee, then re-grant for 1 hour:
+
+  ```bash
+  # revoke now (any past timestamp works)
+  npm run cli authorizeEscrow 0x<token> 0x<payee> 1000 3600 10 --expiry 1
+  # re-authorize, expiring 1h from now
+  npm run cli authorizeEscrow 0x<token> 0x<payee> 1000 3600 10 --expiry $(( $(date +%s) + 3600 ))
+  ```
 
 ---
 
@@ -651,6 +676,29 @@ Notes:
 - **Named Options:**  
   `npm run cli getAuthorizationsEscrow --token 0x1234...tokenAddress --payee 0x5678...payeeAddress`
 
+- Prints the current/max lock limits, current locks, and **(Escrow v2)** the authorization's
+  `expiryTimestamp` (`indefinite (0)`, or the ISO date, flagged `EXPIRED/revoked` when in the past).
+  Note that `Current Locked Amount` now reflects only the **payer-funded** portion of live locks —
+  any provider-sponsored amount lives in the separate sponsored bucket (see `getEscrowInfo`).
+
+---
+
+**Get Escrow Info (Escrow v2):**
+
+- **Positional:**  
+  `npm run cli getEscrowInfo` or `npm run cli getEscrowInfo 0x1234...tokenAddress`
+
+- **Named Options:**  
+  `npm run cli getEscrowInfo --token 0x1234...tokenAddress --chainId 8453`
+
+- Reads the escrow deployment on the active (or `--chainId`) chain via ERC-165 capability
+  discovery and prints: the on-chain `version`, the `escrowKind` (`COMMUNITY` vs `ENTERPRISE`),
+  whether lock-time sponsorship (`IEscrowLockSubsidy`) and the enterprise fee gate
+  (`IEscrowEnterprise`) are supported, and `maxSponsorsPerLock`. When a `token` is supplied it also
+  prints the sponsored-bucket total and your reclaimable amount (lock-subsidy escrows), and the fee
+  collector + whether the token is allowed (enterprise escrows). Works against a legacy (pre-v2)
+  escrow too — it simply reports it as legacy. Alias: `escrowInfo`.
+
 ---
 
 **Create Access List:**
@@ -699,6 +747,48 @@ Notes:
 
 ---
 
+### Subsidy Providers
+
+Subsidy providers are on-chain contracts that sponsor part or all of a job's cost (a subsidy released
+back to the payer, plus an optional bonus paid to the node), subject to allow-lists, job-type
+restrictions and per-period caps. **The Ocean Node is the source of truth for which subsidy providers
+are usable** — a node may not support them at all — so the CLI reads provider addresses from the node's
+status, never from bundled contract addresses.
+
+**See which subsidy providers a node supports:**
+
+- `npm run cli getSubsidyProviders`
+
+  Prints the per-chain subsidy-provider contracts the current node advertises, and whether the node
+  enforces a whitelist on user-supplied providers (`subsidyProviderFilter`). The same info is also shown
+  by `getNode`.
+
+**Check your subsidy limits / remaining credit for a token:**
+
+- **Positional:**  
+  `npm run cli getSubsidyStatus 0x1234...tokenAddress`
+
+- **Named Options:**  
+  `npm run cli getSubsidyStatus --token 0x1234...tokenAddress --chainId 8453 --node 0xNodeAddr --jobType compute --amount 10`
+
+  Discovers the provider contract(s) from the node, then for each prints its kind, per-window buckets
+  (limit / used / remaining / reset), the amount claimable now, the contract's available balance and your
+  eligibility. `--subsidy 0xAddr[,0xAddr2]` narrows to specific node-advertised contract(s);
+  `--node`/`--jobType`/`--amount` together also print a subsidy quote (`{subsidy, bonus}`).
+
+**Choose subsidy providers when starting compute / services:**
+
+- Add `--subsidyProviders <list>` to `startCompute`, `startService`, or `extendService`:
+  - omit the flag → the node uses its configured defaults,
+  - `--subsidyProviders none` (or empty) → claim with **no** subsidy,
+  - `--subsidyProviders 0xA,0xB` → claim against exactly those contracts.
+
+  e.g. `npm run cli startCompute -- did:op:dataset did:op:algo env1 900 0xToken '[...resources...]' --accept true --subsidyProviders 0xA,0xB`
+
+  (`startFreeCompute` ignores subsidy providers — a free job does no escrow claim.)
+
+---
+
 **Allow Algorithm on Dataset:**
 
 - **Positional:**  
@@ -944,12 +1034,18 @@ Notes:
   `-p, --payee <payee>`  
   `-m, --maxLockedAmount <maxLockedAmount>`  
   `-s, --maxLockSeconds <maxLockSeconds>`  
-  `-c, --maxLockCounts <maxLockCounts>`
+  `-c, --maxLockCounts <maxLockCounts>`  
+  `-e, --expiry <timestamp>` (Escrow v2; `0` = indefinite, a past value revokes)  
+  `--chainId <chainId>`
 
 - **getAuthorizationsEscrow:**  
   `-t, --token <token>`  
   `-p, --payee <payee>`
 
+- **getEscrowInfo (escrowInfo):**  
+  `[token]` / `-t, --token <token>`  
+  `--chainId <chainId>`
+
 - **createAccessList:**  
   `-n, --name <name>`  
   `-s, --symbol <symbol>`