escrow subsidy providers

docs/API.md

@@ -872,6 +872,12 @@ returns status of node
       "arwave": true
       "url": true
     },
+    "escrowAddress": {
+      "8996": "0x123"
+    },
+    "subsidyProviders": {
+      "8996": ["0x123", "0x456"]
+    },
     "uptime": 123,
     "platform": {
       "cpus": "123",
@@ -889,6 +895,11 @@ returns status of node
   }
 ```
 
+`escrowAddress` and `subsidyProviders` are per-chain maps (keyed by chainId). `subsidyProviders`
+reflects the node's `SUBSIDY_PROVIDERS` configuration — the Subsidy Provider contract addresses the
+node passes to the escrow at claim time; it is `{}` when none are configured. Both are present in
+the normal and detailed status.
+
 ---
 
 ## Query DDO
@@ -1423,7 +1434,7 @@ Returns indexed Escrow contract events. The indexer matches Escrow logs by topic
 | --------- | ------ | --------- | --------------------------------------------------------- |
 | command   | string | POST only | command name (`getEscrowEvents`)                          |
 | chainId   | number |           | chain id                                                  |
-| eventType | string |           | one of `Auth, Lock, Claimed, Canceled, Deposit, Withdraw` |
+| eventType | string |           | one of `Auth, Lock, ReLock, Claimed, Canceled, Deposit, Withdraw, Subsidized` |
 | payer     | string |           | payer address (case-insensitive)                          |
 | payee     | string |           | payee address (case-insensitive)                          |
 | token     | string |           | token address (case-insensitive)                          |
@@ -1446,7 +1457,7 @@ Returns indexed Escrow contract events. The indexer matches Escrow logs by topic
 
 #### Response
 
-Every row has `id, eventType, chainId, contract, block, txHash` plus event-specific fields (`payer, payee, token, jobId, amount, expiry, proof, maxLockedAmount, maxLockSeconds, maxLockCounts`).
+Every row has `id, eventType, chainId, contract, block, txHash` plus event-specific fields (`payer, payee, token, jobId, amount, expiry, proof, maxLockedAmount, maxLockSeconds, maxLockCounts`). A `Subsidized` row (emitted once per contributing Subsidy Provider at claim time) additionally carries `provider, subsidyAmount, bonusAmount`.
 
 ```json
 [

docs/env.md

@@ -56,6 +56,7 @@ Environmental variables are also tracked in `ENVIRONMENT_VARIABLES` within `src/
 ## Payments
 
 - `ESCROW_CLAIM_TIMEOUT`: Amount of time reserved to claim a escrow payment, in seconds. Defaults to `3600`. Example: `3600`
+- `SUBSIDY_PROVIDERS`: Per-chain map (keyed by chainId) of Subsidy Provider contract addresses the node passes to the escrow at claim time, so a third party can sponsor part of a payer's cost and/or pay the node a bonus. Each chain's value is a list, so several providers can be named per chain. The addresses are normalized to their EIP-55 checksummed form; a malformed value (bad JSON, not a per-chain object, or an invalid address) is ignored (the whole map is treated as unset) rather than blocking startup. Defaults to unset (no subsidies; plain claims). Example — use the OPF Subsidy Provider on Base (chainId `8453`): `"{ \"8453\": [\"0x4344D4Bc29531DB736378e9A3dA85BF1eff0CB22\"] }"`. Multiple chains/providers: `"{ \"8453\": [\"0x4344D4Bc29531DB736378e9A3dA85BF1eff0CB22\"], \"8996\": [\"0x123\",\"0x456\"] }"`
 
 ## Logs
 

package.json

@@ -75,7 +75,7 @@
     "@libp2p/utils": "^7.4.1",
     "@libp2p/websockets": "^10.1.21",
     "@multiformats/multiaddr": "^13.0.3",
-    "@oceanprotocol/contracts": "^2.9.0",
+    "@oceanprotocol/contracts": "^3.0.0",
     "@oceanprotocol/ddo-js": "^0.4.1",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",

src/@types/Escrow.ts

@@ -35,4 +35,8 @@ export interface EscrowEvent {
   oldAmount?: string
   newAmount?: string
   newExpiry?: string
+  // Subsidized event fields
+  provider?: string
+  subsidyAmount?: string
+  bonusAmount?: string
 }

src/@types/OceanNode.ts

@@ -177,6 +177,8 @@ export interface OceanNodeConfig {
   assetPurgatoryUrl: string | null
   allowedAdmins?: string[]
   allowedAdminsList?: AccessListContract | null
+  // per-chain map of Subsidy Provider contract addresses passed to the escrow at claim time
+  subsidyProviders?: AccessListContract | null
   codeHash?: string
   rateLimit?: number // per request ip or peer
   maxConnections?: number // global, regardless of client address(es)
@@ -264,6 +266,8 @@ export interface OceanNodeStatus {
   uptime?: number // seconds since start
   codeHash?: string
   allowedAdmins?: { addresses: string[]; accessLists: AccessListContract }
+  // per-chain map of Subsidy Provider contract addresses configured on this node
+  subsidyProviders?: AccessListContract
   // detailed information
   c2dClusters?: any[]
   supportedSchemas?: Schema[]

src/OceanNode.ts

@@ -79,7 +79,8 @@ export class OceanNode {
       this.escrow = new Escrow(
         this.config.supportedNetworks,
         this.config.claimDurationTimeout,
-        this.blockchainRegistry
+        this.blockchainRegistry,
+        this.config.subsidyProviders
       )
       if (this.config.persistentStorage?.enabled) {
         OCEAN_NODE_LOGGER.info(
@@ -281,7 +282,8 @@ export class OceanNode {
       this.escrow = new Escrow(
         this.config.supportedNetworks,
         this.config.claimDurationTimeout,
-        this.blockchainRegistry
+        this.blockchainRegistry,
+        this.config.subsidyProviders
       )
     }
   }

src/components/Indexer/processor.ts

@@ -50,7 +50,8 @@ const EVENT_PROCESSOR_MAP: Record<string, ProcessorConstructor> = {
   [EVENTS.ESCROW_CLAIMED]: EscrowEventProcessor,
   [EVENTS.ESCROW_CANCELED]: EscrowEventProcessor,
   [EVENTS.ESCROW_DEPOSIT]: EscrowEventProcessor,
-  [EVENTS.ESCROW_WITHDRAW]: EscrowEventProcessor
+  [EVENTS.ESCROW_WITHDRAW]: EscrowEventProcessor,
+  [EVENTS.ESCROW_SUBSIDIZED]: EscrowEventProcessor
 }
 
 const processorInstances = new Map<string, BaseEventProcessor>()

src/components/Indexer/processors/EscrowEventProcessor.ts

@@ -100,6 +100,16 @@ export class EscrowEventProcessor extends BaseEventProcessor {
           record.token = addr(args.token)
           record.amount = num(args.amount)
           break
+        case EVENTS.ESCROW_SUBSIDIZED:
+          // Subsidized(payee, payer, jobId, token, provider, subsidyAmount, bonusAmount)
+          record.payee = addr(args.payee)
+          record.payer = addr(args.payer)
+          record.jobId = num(args.jobId)
+          record.token = addr(args.token)
+          record.provider = addr(args.provider)
+          record.subsidyAmount = num(args.subsidyAmount)
+          record.bonusAmount = num(args.bonusAmount)
+          break
         default:
           return null
       }

src/components/c2d/compute_engine_docker.ts

@@ -51,7 +51,7 @@ import {
 } from 'fs'
 import { pipeline } from 'node:stream/promises'
 import { CORE_LOGGER } from '../../utils/logging/common.js'
-import { ENVIRONMENT_VARIABLES } from '../../utils/constants.js'
+import { ENVIRONMENT_VARIABLES, JobType } from '../../utils/constants.js'
 import { AssetUtils } from '../../utils/asset.js'
 import { FindDdoHandler } from '../core/handler/ddoHandler.js'
 import { OceanNode } from '../../OceanNode.js'
@@ -1011,7 +1011,8 @@ export class C2DEngineDocker extends C2DEngine {
             tokens,
             payers,
             amounts,
-            proofs
+            proofs,
+            JobType.COMPUTE
           )
           if (txId) {
             // Update all jobs with the transaction ID
@@ -1041,7 +1042,8 @@ export class C2DEngineDocker extends C2DEngine {
                 claim.job.payment!.token,
                 claim.job.owner,
                 claim.cost,
-                claim.proof
+                claim.proof,
+                JobType.COMPUTE
               )
               if (txId) {
                 if (claim.job.payment) {
@@ -4133,7 +4135,8 @@ export class C2DEngineDocker extends C2DEngine {
         token,
         job.owner,
         job.payment.cost,
-        `service-start:${serviceId}`
+        `service-start:${serviceId}`,
+        JobType.SERVICE
       )
       if (!claimTx) {
         job.payment.cancelTx = await this.safeCancelLock(

src/components/core/service/extendService.ts

@@ -9,6 +9,7 @@ import {
   buildInvalidRequestMessage
 } from '../../httpRoutes/validateCommands.js'
 import { CORE_LOGGER } from '../../../utils/logging/common.js'
+import { JobType } from '../../../utils/constants.js'
 import type { ComputeEnvironment } from '../../../@types/C2D/C2D.js'
 import { ServiceStatusNumber } from '../../../@types/C2D/ServiceOnDemand.js'
 import { validateAccess } from '../compute/startCompute.js'
@@ -330,7 +331,8 @@ export class ServiceExtendHandler extends CommandHandler {
               task.payment.token,
               task.consumerAddress,
               costExtend,
-              `service-extend:${task.serviceId}`
+              `service-extend:${task.serviceId}`,
+              JobType.SERVICE
             )
           } catch (e: any) {
             claimTx = null

src/components/core/utils/escrow.ts

@@ -4,6 +4,8 @@ import EscrowJson from '@oceanprotocol/contracts/artifacts/contracts/escrow/Escr
 import { EscrowAuthorization, EscrowLock } from '../../../@types/Escrow.js'
 import { getOceanArtifactsAdressesByChainId } from '../../../utils/address.js'
 import { RPCS } from '../../../@types/blockchain.js'
+import { AccessListContract } from '../../../@types/OceanNode.js'
+import { JobType } from '../../../utils/constants.js'
 import { create256Hash } from '../../../utils/crypt.js'
 import { sleep } from '../../../utils/util.js'
 import { BlockchainRegistry } from '../../BlockchainRegistry/index.js'
@@ -17,17 +19,29 @@ export class Escrow {
   private networks: RPCS
   private claimDurationTimeout: number
   private blockchainRegistry: BlockchainRegistry
+  /** Per-chain Subsidy Provider contract addresses, passed to the escrow at claim time. */
+  private subsidyProviders: AccessListContract | null
   /** Cache for token decimals to avoid repeated blockchain calls */
   private decimalsCache: Map<string, number> = new Map()
 
   constructor(
     supportedNetworks: RPCS,
     claimDurationTimeout: number,
-    blockchainRegistry: BlockchainRegistry
+    blockchainRegistry: BlockchainRegistry,
+    subsidyProviders: AccessListContract | null = null
   ) {
     this.networks = supportedNetworks
     this.claimDurationTimeout = claimDurationTimeout
     this.blockchainRegistry = blockchainRegistry
+    this.subsidyProviders = subsidyProviders
+  }
+
+  /**
+   * Subsidy Provider contract addresses configured for a given chain, or an empty list when none
+   * are set. The empty list is the "plain claim" case the escrow expects (no third-party subsidy).
+   */
+  private getSubsidyProvidersForChain(chain: number): string[] {
+    return this.subsidyProviders?.[String(chain)] ?? []
   }
 
   getEscrowContractAddressForChain(chainId: number): string | null {
@@ -236,13 +250,15 @@ export class Escrow {
     token: string,
     payer: string,
     amount: number,
-    proof: string
+    proof: string,
+    jobType: JobType = JobType.NONE
   ): Promise<string | null> {
     const blockchain = this.getBlockchain(chain)
     const signer = await blockchain.getSigner()
     const contract = this.getContract(chain, signer)
     const wei = await this.getPaymentAmountInWei(amount, chain, token)
     const jobId = create256Hash(job)
+    const subsidyProviders = this.getSubsidyProvidersForChain(chain)
     if (!contract) return null
     try {
       const locks = await this.getLocks(chain, token, payer, await signer.getAddress())
@@ -253,7 +269,9 @@ export class Escrow {
             token,
             payer,
             wei,
-            ethers.toUtf8Bytes(proof)
+            ethers.toUtf8Bytes(proof),
+            jobType,
+            subsidyProviders
           )
           const gasOptions = await blockchain.getGasOptions(gas, 1.2)
           const tx = await contract.claimLockAndWithdraw(
@@ -262,6 +280,8 @@ export class Escrow {
             payer,
             wei,
             ethers.toUtf8Bytes(proof),
+            jobType,
+            subsidyProviders,
             gasOptions
           )
           return tx.hash
@@ -321,7 +341,8 @@ export class Escrow {
     tokens: string[],
     payers: string[],
     amounts: number[],
-    proofs: string[]
+    proofs: string[],
+    jobType: JobType = JobType.NONE
   ): Promise<string | null> {
     const blockchain = this.getBlockchain(chain)
     const signer = await blockchain.getSigner()
@@ -345,13 +366,21 @@ export class Escrow {
       jobIds.push(jobId)
       ethProofs.push(ethers.toUtf8Bytes(proofs[i]))
     }
+    // Parallel arrays the plural claim ABI expects: one jobType per job (all the same here) and
+    // one subsidy-provider list per job (the batch is single-chain, so the same per-chain list is
+    // repeated for every job).
+    const chainSubsidyProviders = this.getSubsidyProvidersForChain(chain)
+    const jobTypes: JobType[] = jobs.map(() => jobType)
+    const subsidyProviders: string[][] = jobs.map(() => chainSubsidyProviders)
     try {
       const gas = await contract.claimLocksAndWithdraw.estimateGas(
         jobIds,
         tokens,
         payers,
         weis,
-        ethProofs
+        ethProofs,
+        jobTypes,
+        subsidyProviders
       )
       const gasOptions = await blockchain.getGasOptions(gas, 1.2)
       const tx = await contract.claimLocksAndWithdraw(
@@ -360,6 +389,8 @@ export class Escrow {
         payers,
         weis,
         ethProofs,
+        jobTypes,
+        subsidyProviders,
         gasOptions
       )
       return tx.hash

src/components/core/utils/statusHandler.ts

@@ -148,6 +148,10 @@ export async function status(
       )
     }
   }
+  // Per-chain Subsidy Provider contract addresses configured on this node (empty map when none
+  // are set). Set on every request, independent of supportedNetworks, so the field is always
+  // present and never retains a stale value the config no longer defines.
+  nodeStatus.subsidyProviders = config.subsidyProviders ?? {}
   // Whether the P2P interface is usable, not just enabled. Re-read on every request rather
   // than cached with the block above: the routing table fills after startup, so a value
   // captured once would report a node as permanently not-ready.

src/test/integration/download.test.ts

@@ -75,6 +75,7 @@ describe('**********         [Download Flow] - Should run a complete node flow.'
           ENVIRONMENT_VARIABLES.PRIVATE_KEY,
           ENVIRONMENT_VARIABLES.AUTHORIZED_DECRYPTERS,
           ENVIRONMENT_VARIABLES.ALLOWED_ADMINS,
+          ENVIRONMENT_VARIABLES.SUBSIDY_PROVIDERS,
           ENVIRONMENT_VARIABLES.ADDRESS_FILE
         ],
         [
@@ -83,6 +84,7 @@ describe('**********         [Download Flow] - Should run a complete node flow.'
           '0xc594c6e5def4bab63ac29eed19a134c130388f74f019bc74b8f4389df2837a58',
           JSON.stringify(['0xe2DD09d719Da89e5a3D0F2549c7E24566e947260']),
           JSON.stringify(['0xe2DD09d719Da89e5a3D0F2549c7E24566e947260']),
+          JSON.stringify({ '8996': ['0xe2DD09d719Da89e5a3D0F2549c7E24566e947260'] }),
           `${homedir}/.ocean/ocean-contracts/artifacts/address.json`
         ]
       )
@@ -127,6 +129,11 @@ describe('**********         [Download Flow] - Should run a complete node flow.'
         '0xe2DD09d719Da89e5a3D0F2549c7E24566e947260'?.toLowerCase(),
       'incorrect admin address'
     )
+    assert(
+      status.subsidyProviders?.['8996']?.[0]?.toLowerCase() ===
+        '0xe2DD09d719Da89e5a3D0F2549c7E24566e947260'?.toLowerCase(),
+      'incorrect subsidy provider address'
+    )
     assert(status.c2dClusters === undefined, 'clusters info should be undefined')
     assert(status.supportedSchemas === undefined, 'schemas info should be undefined')
   })
@@ -142,6 +149,11 @@ describe('**********         [Download Flow] - Should run a complete node flow.'
     const status = JSON.parse(resp)
     assert(status.c2dClusters !== undefined, 'clusters info should not be undefined')
     assert(status.supportedSchemas !== undefined, 'schemas info should not be undefined')
+    assert(
+      status.subsidyProviders?.['8996']?.[0]?.toLowerCase() ===
+        '0xe2DD09d719Da89e5a3D0F2549c7E24566e947260'?.toLowerCase(),
+      'subsidy providers should be present in detailed status'
+    )
   })
 
   it('should get file info before publishing', async () => {