feat: add trace-offer #795

foufrix · 2025-10-28T15:30:00Z

Implement traceOffer function.

It should return an object with this form:

export type OfferTrace = {
  success?: boolean[]
  declined?: boolean
  failed?: boolean
}

Function have exactly the same behavior as offer, the difference is on what it returns.

A helper function to convert bit to boolean array has been added to improve reusability. For the moment it's in portal.ts maybe there is a better place to put this helper?

Test case has been added where we try 3 cases:

success
peer not interested
peer not reacheable (wrong enr)

This solve #729

ScottyPoi

Thanks for the PR!
We have not been developing on Ultralight recently, as we evaluate the future of Portal Network in general. Reviewing this with some optimism that some version of Portal will still be used by EL clients.

Good work overall. I left a few comments to address. There's a bug in how the new RPC methods are dealing with the response. I'll take some blame there, as the upgrade to protocol V1 was not well documented in the code. The upgrade from v0 to v1 involved changing the return type of the contentKeys array in an ACCEPT response. With v0 we used a BitArray, and with V1 it is a Unit8Array. Currently things are set up to support both versions, so we'll need to handle the reponse differently if it's a BitArray or Uint8Array for now, and you won't want to call your helper function on a Uint8Array response.

ScottyPoi · 2025-10-29T21:54:47Z

packages/cli/src/rpc/modules/portal.ts

 import type { BeaconNetwork, HistoryNetwork, PortalNetwork, StateNetwork } from 'portalnetwork'
 import type { GetEnrResult } from '../schema/types.js'

+/**


can we move this to rpc/utils.ts?

thanks that's the info I was looking for 🙏

ScottyPoi · 2025-10-29T22:08:47Z

packages/cli/test/rpc/portal/historyTraceOffer.spec.ts

+
+      // Should return success with boolean array indicating which keys were accepted
+      assert.ok(res.result.success !== undefined, 'should have success array')
+      if (res.result.success === true) {


res.result.success is a boolean array, so this part gets skipped

you've already asserted that it is not undefined, so you can just remove this conditional and let the other checks happen

ScottyPoi · 2025-10-29T22:28:22Z

packages/cli/src/rpc/modules/portal.ts

+      }
+
+      const res = await this._history.sendOffer(enr, contentKeys, contentValues)
+      return bitToBooleanArray(res, contentKeys.length)


The response will only be a BitArray if running protocol V0

With V1 this type was changed to Uint8Array. The current state of Ultralight is still designed to support both.

But if the response is V1 you won't want to call this helper function, which would actually end up returning a full array of accepts.

ok, let me see and update accordingly to support both

ScottyPoi · 2025-10-29T22:28:46Z

packages/cli/src/rpc/modules/portal.ts

+      }
+
+      const res = await this._state.sendOffer(enr, contentKeys, contentValues)
+      return bitToBooleanArray(res, contentKeys.length)


Same here as history method

ScottyPoi · 2025-10-29T22:28:56Z

packages/cli/src/rpc/modules/portal.ts

+      }
+
+      const res = await this._beacon.sendOffer(enr, contentKeys, contentValues)
+      return bitToBooleanArray(res, contentKeys.length)


same here as history method

packages/cli/src/rpc/modules/portal.ts

change any to BitArray type Co-authored-by: Scotty <[email protected]>

…ralight into feat-add-trace-offer

packages/cli/src/rpc/modules/portal.ts

foufrix · 2025-10-30T14:57:16Z

@ScottyPoi thanks for the review:

test case fixed by removing useless if statement
function move to rpc/utils
new function to manage UInt8 to boolean array
trigger the correct function depending of typeof res

Can you confirm what should be return in case we don't have UInt8Array or BitArray 🙏

Also I should not continue to take other issue if project is on halt? Where can I follow the state of decision for the future of Portal Network?

packages/cli/src/rpc/util.ts

ScottyPoi · 2025-10-30T21:35:16Z

packages/cli/test/rpc/portal/historyTraceOffer.spec.ts

+    // Store content in node2
+    await rp2.request('portal_historyStore', [contentKey1, content1])
+    await rp2.request('portal_historyStore', [contentKey2, content2])


If node2 stores these contents first, it will reject them in the OFFER. This test is giving you a false positive because of the bug in the Uint8ToBooleanArray helper

ScottyPoi · 2025-10-30T22:54:30Z

Can you confirm what should be return in case we don't have UInt8Array or BitArray 🙏

sendOffer will return undefined if there is a version mismatch, or throw an error if the message doesn't send for some reason. I think we would return "failed" in these circumstances, but double check the specs for this method.

Also I should not continue to take other issue if project is on halt? Where can I follow the state of decision for the future of Portal Network?

The original set of Portal Networks are now "Legacy" and no longer live. The only Portal Network currently in development is a new, minimal version of history. I'm going to rename all of the old networks with a Legacy tag. I don't want to remove them, in case there is a revival at some point.

The work you're doing now is still helpful though! I plan to implement the new ExecutionHistoryNetwork, which you're welcome to help with, and adding a traceOffer method for that network will be simple since

check only AccetCode in UInt8toBoolenArray Co-authored-by: Scotty <[email protected]>

foufrix and others added 6 commits October 28, 2025 16:04

feat: add TraceOffer function

974f988

create a helper function converting bit to boolean array

004a97f

fix: testcase should not fail for success

2e5054b

fix type

cb97fa5

Merge branch 'master' into feat-add-trace-offer

b587fa1

fix type with existing one

721f294

ScottyPoi reviewed Oct 29, 2025

View reviewed changes

ScottyPoi and others added 6 commits October 29, 2025 16:39

add return type to sendOffer method

49bb49c

Update packages/cli/src/rpc/modules/portal.ts

a9f8eba

change any to BitArray type Co-authored-by: Scotty <[email protected]>

fix: move bitToBooleanArray to rpc/utils

0ce39a0

fix: remove useless if assessment in test

522eb43

feat: add V1 case where response is Uint8Array

fbc3a1d

Merge branch 'feat-add-trace-offer' of https://github.com/foufrix/ult…

6ba3931

…ralight into feat-add-trace-offer

foufrix commented Oct 30, 2025

View reviewed changes

packages/cli/src/rpc/modules/portal.ts Show resolved Hide resolved

ScottyPoi reviewed Oct 30, 2025

View reviewed changes

packages/cli/src/rpc/util.ts Show resolved Hide resolved

ScottyPoi reviewed Oct 30, 2025

View reviewed changes

foufrix and others added 2 commits October 31, 2025 10:15

Update packages/cli/src/rpc/util.ts

2476bd0

check only AccetCode in UInt8toBoolenArray Co-authored-by: Scotty <[email protected]>

fix: import AcceptCode

29f2ba0

feat: add trace-offer #795

Are you sure you want to change the base?

feat: add trace-offer #795

Uh oh!

Conversation

foufrix commented Oct 28, 2025

Uh oh!

ScottyPoi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

foufrix commented Oct 30, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ScottyPoi commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants