user-selectable subsidy providers

[alexcos20]

Feat: user-selectable subsidy providers (compute & services)

Problem

Ocean Node #1485 lets a consumer choose
which subsidy provider contracts receive the claim for a paid job, instead of relying solely on
the node operator's configuration. The node accepts an optional subsidyProviders: string[] on three
requests — startCompute (paid), serviceStart, and serviceExtend — and resolves it tri-state:

• omitted → the node uses its configured providers,
• [] (empty array) → explicitly no subsidy provider,
• populated → only those addresses, subject to the node's SUBSIDY_PROVIDER_FILTER policy.

Free compute accepts the field but ignores it (no escrow claim occurs).

ocean.js had no way to send this field, so consumers couldn't select providers from the client. This
PR threads subsidyProviders through the client's compute and service-on-demand surface.

Approach

ocean.js's Provider is a transport-dispatching façade (BaseProvider) over HttpProvider (REST)
and P2pProvider (libp2p). The field is forwarded verbatim at the top level of the request body on
whichever transport is in use — the library stays a thin wrapper and lets the node own validation
(EIP-55 checks, whitelist filtering, DoS caps).

The field is optional and additive: existing call sites keep working unchanged.

• serviceStart carries it on the ServiceStartParams object, so no method signature changes —
  both transports already spread ...rest of the params into the request body, forwarding it for free.
• computeStart gains a new trailing optional parameter (subsidyProviders?: string[]), kept last
  so no existing positional argument shifts.
• serviceExtend gains the optional parameter after signal (an integration test already
  passes signal positionally, so inserting before it would break that caller).

Empty-array semantics are preserved on the wire: [] is truthy in JS, so the client transmits it,
letting the node distinguish "no subsidy provider" from "use the default".

Changes

1. Types — src/@types/Services.ts

• Added subsidyProviders?: string[] to ServiceStartParams, documenting the tri-state resolution.

2. Compute — computeStart

• HttpProvider, P2pProvider, BaseProvider: new trailing optional subsidyProviders?: string[]
  parameter, added to the request body only when supplied. BaseProvider passes it through to the
  selected transport.

3. Services on demand — serviceStart / serviceExtend

• serviceStart: forwarded via ServiceStartParams (no signature change).
• serviceExtend: HttpProvider, P2pProvider, BaseProvider gain the optional parameter after
  signal, added to the request body when supplied.

4. Tests — test/unit/SubsidyProviders.test.ts

• Hermetic unit tests (no chain / no barge) that stub fetch and assert the wire contract for all
  three endpoints:
  • the field is forwarded when supplied,
  • it is omitted when not supplied,
  • an empty array is transmitted (tri-state).
• An agent signature short-circuits the nonce round-trip, so the only network call is the captured
  request.

Why it's safe

• Additive & backwards-compatible. One new optional type field + trailing optional parameters; no
  existing call signature changes and no existing caller shifts positionally.
• Thin passthrough. The node remains the source of truth for address validation, whitelist
  filtering (SUBSIDY_PROVIDER_FILTER) and any list-size caps — the client doesn't duplicate policy.
• Free compute untouched. freeComputeStart deliberately does not send the field, since the node
  ignores it there.

Summary by CodeRabbit

• New Features
  • Added an optional provider list for compute starts and service extensions. You can use it to select specific subsidy providers or pass an empty list to disable them; leaving it unspecified uses the node’s configured providers.
• Tests
  • Added coverage for how provider lists are included or omitted in requests.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 18601bca-4c7d-485f-8cee-1a6269be4daa

📥 Commits

Reviewing files that changed from the base of the PR and between a518ec2 and 3d36789.

📒 Files selected for processing (5)

• src/@types/Services.ts
• src/services/providers/BaseProvider.ts
• src/services/providers/HttpProvider.ts
• src/services/providers/P2pProvider.ts
• test/unit/SubsidyProviders.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

---

📝 Walkthrough

Walkthrough

The SDK adds an optional subsidyProviders list to service parameters and forwards it through HTTP and P2P provider requests. The list can be omitted, empty, or populated. Unit tests check request-body handling for these cases.

Changes

Subsidy provider forwarding

Layer / File(s)	Summary
Add subsidy provider parameters src/@types/Services.ts, src/services/providers/BaseProvider.ts	ServiceStartParams adds optional subsidyProviders. BaseProvider accepts and forwards the list for compute start and service extension.
Forward providers in transport requests src/services/providers/HttpProvider.ts, src/services/providers/P2pProvider.ts, test/unit/SubsidyProviders.test.ts	HTTP and P2P transports add supplied provider lists to request payloads. Tests check supplied and omitted values, and verify that an empty array is forwarded.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Consumer
  participant BaseProvider
  participant HttpProvider
  participant P2pProvider
  participant Node
  Consumer->>BaseProvider: Call computeStart or serviceExtend with subsidyProviders
  alt HTTP transport selected
    BaseProvider->>HttpProvider: Forward subsidyProviders
    HttpProvider->>Node: Send request payload
  else P2P transport selected
    BaseProvider->>P2pProvider: Forward subsidyProviders
    P2pProvider->>Node: Send request payload
  end

Loading

Merge Risk: ⚪ Minimal · up to 3d367

No issue requiring correction before merge is established for subsidy-provider forwarding.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: allowing users to select subsidy providers. It is concise and directly related to the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 5…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[alexcos20]

/run-security-scan

[alexcos20]

AI automated code review (Gemini 3).

Overall risk: low

Summary:
This PR successfully introduces support for user-selectable subsidy providers in ocean.js. The architectural approach preserves backward compatibility by appending optional parameters to existing methods. The tri-state logic (omitted, empty array, populated array) is correctly implemented by relying on JavaScript's array truthiness to distinguish between undefined and []. The addition of dedicated unit tests to lock down the wire contract behavior is excellent. LGTM!

Comments:
• [INFO][other] The comment properly documents that EIP-55 addresses are expected. While the ocean-node backend will validate these, you might consider adding lightweight client-side validation in the future (e.g., using a quick regex or web3 utility) to fail fast and prevent unnecessary network calls when invalid formats are provided.
• [INFO][style] Using if (subsidyProviders) elegantly leverages JavaScript's evaluation of objects, ensuring that an empty array [] evaluates to true and is included in the payload. This successfully satisfies the tri-state requirement to explicitly send [] when users want no subsidy providers. Great work ensuring this nuance was tested!