Add signed peer record transfer support in circuit-relay V2 protocol. #848

Antrikshgwal · 2025-08-16T14:42:10Z

What was wrong?

As tracked by #791, the Relay V2 protocol needs to support Signed Peer Record (SPR) transfer to establish secure and verifiable connection between peers relayed through intermediaries. Currently, Circuit Relay V2 only handles HOP and STOP requests without propagating authenticated peer information.

Issue #847

How was it fixed?

This WIP PR aims to:

Extend the Circuit Relay V2 protobuf definitions to include an optional signed_peer_record field in HOP and STOP messages.
Implement handlers in the Relay V2 module to:
Send the local peer’s SPR along with HOP and STOP requests.
Receive and verify incoming SPRs against the peer’s PeerId.
Validate that relayed connections are only established when valid SPRs are exchanged.

This design follows the integration strategy used in KAD-DHT and Gossipsub, ensuring consistency across protocols.

The goal is to improve the trustworthiness of peer discovery and relay connections by embedding verifiable identity metadata directly in Relay V2 message flows.

To-Do

Clean up commit history
Add or update documentation related to these changes
Add entry to the release notes

Cute Animal Picture

lla-dane · 2025-08-17T09:08:06Z

@Antrikshgwal
When you updated the .proto file and recompiled it, the circui_pb2.pyi file should also have been changed, which has not. Make sure you are using this command:

protoc --proto_path=. --python_out=. --pyi_out=. `libp2p/relay/circuit_v2/pb/circuit.proto`

Now further, you should set up the following utilities in the curcuit_v2 module:

maybe_consume_signed_record: For consuming the received records in requests/responses
env_to_send_in_RPC and issue_and_cache_local_record: For issuing a signed-record which broadcasting a message.

For reference, look at libp2p/kad_dht/utils.py file in #815

After that you should look for code-snippets where a HopMessage or StopMessage is received like these:

response_bytes = await stream.read()
if not response_bytes:
  logger.error("No response received from relay %s", peer_id)
  return False

# Parse response
response = HopMessage()
response.ParseFromString(response_bytes)

# Check if reservation was successful
if response.type == HopMessage.RESERVE and response.HasField(
  "status"
):

and add the maybe_consume_signed_record in the way to process the sent record like this:

# Consume the source signed_peer_record if sent
if not maybe_consume_signed_record(message, self.host):
    logger.error(
        "Received an invalid-signed-record, dropping the stream"
    )
    await stream.close()
    return

And in the same way, when we are braodcasting messages, you need to send a singned-record via the env_to_send_in_RPC function.

Now an example of how I did it in dht:

 # Add sender's signed-peer-record
envelope_bytes, bool = env_to_send_in_RPC(self.host)
response.senderRecord = envelope_bytes

You have to add these while we are sending you requests and responses both.
So basically when we receive a message, you need to maybe_consume_peer_record and when we broadcast message, you need to attach a signed-record with the message

CCing @seetadev

seetadev · 2025-08-17T11:01:50Z

@Antrikshgwal and @lla-dane : This is excellent work — really glad to see steady progress on bringing Signed Peer Record (SPR) support into Circuit Relay V2. Completely agree with the design: without SPR propagation, relayed peers don’t have a verifiable identity layer, and that leaves gaps in the trust model.

Extending the protocol to carry signed_peer_record in HOP/STOP flows is exactly the right direction, and it aligns well with the precedent we already have in KAD-DHT and Gossipsub. That consistency across protocols will make adoption and reasoning about peer identity much smoother.

Appreciate the concrete steps outlined in the WIP PR:

Updating the protobuf definitions with optional signed_peer_record.

Implementing both sending and verifying SPRs in HOP/STOP handlers.

Enforcing that relayed connections only succeed when records are valid.

This design ensures that relay connections carry the same authenticity guarantees as direct connections, which is a big step forward for overall security.

@lla-dane’s feedback on implementation steps is indeed very important — especially around integrating maybe_consume_signed_record, env_to_send_in_RPC, and issue_and_cache_local_record.

These utilities have already proven reliable in DHT, so reusing the same patterns here is a smart move. Adding these hooks in the message receive/send paths for HOP and STOP will give us robust, testable behavior.

Looking forward to the rebased PR with the protobuf updates, SPR utilities wired in, and commit history tidied up. Great momentum here — keep it up!

seetadev · 2025-08-17T11:02:23Z

@lla-dane and @Antrikshgwal : Ran the CI/CD pipeline. Please take your time in resolving the issues.

Antrikshgwal · 2025-08-20T19:14:21Z

Hey @seetadev! I have a doubt, according to the proto file I pushed, we are sending records in the hop messages and receiving records in the stop messages. Then, according to the diagram, Peer B can't receive records of Peer A through the relay circuit. I am not sure if it is the intended behaviour.
I guessed that maybe after establishing a switched connection, B can get the records from A, so it is not important to send through the relay. Please clarify.

lla-dane · 2025-08-23T13:30:30Z

libp2p/relay/circuit_v2/utils.py

+def issue_and_cache_local_record(host: IHost) -> bytes:
+    env = create_signed_peer_record(
+        host.get_id(),
+        host.get_addrs(),
+        host.get_private_key(),
+    )
+    # Cache it for next time use
+    host.get_peerstore().set_local_record(env)
+    return env.marshal_envelope()
+
+
+def env_to_send_in_RPC(host: IHost) -> tuple[bytes, bool]:
+    listen_addrs_set = {addr for addr in host.get_addrs()}
+    local_env = host.get_peerstore().get_local_record()
+
+    if local_env is None:
+        # No cached SPR yet -> create one
+        return issue_and_cache_local_record(host), True
+    else:
+        record_addrs_set = local_env._env_addrs_set()
+        if record_addrs_set == listen_addrs_set:
+            # Perfect match -> reuse cached envelope
+            return local_env.marshal_envelope(), False
+        else:
+            # Addresses changed -> issue a new SPR and cache it
+            return issue_and_cache_local_record(host), True


Move these 2 functions to peer/peerstore.py file, as done in #835 and #815, and add docstrings for this function too.

lla-dane · 2025-08-23T13:34:35Z

libp2p/relay/circuit_v2/utils.py

+def maybe_consume_signed_record(msg: HopMessage | StopMessage, host: IHost) -> bool:
+    if isinstance(msg, StopMessage):
+        if msg.HasField("senderRecord"):
+            try:
+                # Convert the signed-peer-record(Envelope) from
+                # protobuf bytes
+                envelope, _ = consume_envelope(
+                    msg.senderRecord,
+                    "libp2p-peer-record",
+                )
+                # Use the default  TTL of 2 hours (7200 seconds)
+                if not host.get_peerstore().consume_peer_record(envelope, 7200):
+                    logger.error("Updating the certified-addr-book was unsuccessful")
+            except Exception as e:
+                logger.error("Error updating the certified addr book for peer: %s", e)
+                return False
+    elif isinstance(msg,HopMessage):
+        if msg.HasField("signedRecord"):
+            try:
+                # Convert the signed-peer-record(Envelope) from
+                # protobuf bytes
+                envelope, _ = consume_envelope(
+                    msg.signedRecord,
+                    "libp2p-peer-record",
+                )
+                # Use the default TTL of 2 hours (7200 seconds)
+                if not host.get_peerstore().consume_peer_record(envelope, 7200):
+                    logger.error("Failed to update the Certified-Addr-Book")
+            except Exception as e:
+                logger.error(
+                    "Error updating the certified-addr-book: %s",
+                    e,
+                )
+                return False
+    return True


Add docstrings for this function. Add the checker for verifying if the peer-id who sent the record is same as the senderRecord's peer id. Refer the corresponding function in #815.

seetadev · 2025-08-25T14:26:02Z

@Antrikshgwal : Hi Antriksh. Thank you for submitting the PR and making improvements. Appreciate it.

Please resolve the CI/CD issues. CCing @lla-dane and @sumanjeet0012, who will help you arrive at a good conclusion on the issue.

Also, please add the test suite like the one @lla-dane added for adding signed peer record transfer support in kad-dht and pub-sub/gossipsub. Please consult with @lla-dane in detail as you make improvements.

sumanjeet0012 · 2025-08-29T10:00:26Z

The CI/CD pipeline currently has a couple of issues:

1. Failing Test Cases

Currently 4 circuit relay tests are failing

you can test locally before pushing changes using:

pytest <path/to/file or directory>

2. Linting Issues

There are several linting issues:

Run the following command locally to automatically fix resolvable issues:

pre-commit run --all-files

Manually address any remaining issues that cannot be automatically resolved

3. Documentation Issue

Status: Module import error during documentation generation

Error Message:

WARNING: autodoc: failed to import module 'relay' from module 'libp2p'; the following exception was raised:

Root Cause: The relay module is not properly available in libp2p

Solution:
Create __init__.py files in the following directories:

libp2p/relay/
libp2p/relay/pb/

@Antrikshgwal Let me know if you need any help.

Antrikshgwal · 2025-08-30T14:17:58Z

Create __init__.py files in the following directories:

libp2p/relay/

libp2p/relay/pb/

Hi @sumanjeet0012
These directories already have __init__.py files.

"shift create_signed_records in peerstore"

seetadev · 2025-08-30T15:38:47Z

@Antrikshgwal : Hi Antriksh. Re-ran the CI/CD pipeline.

Please resolve the CI/CD issues. CCing @lla-dane and @sumanjeet0012, who will help you arrive at a good conclusion on the issue.

Also, please add the test suite like the one @lla-dane added for adding signed peer record transfer support in kad-dht and pub-sub/gossipsub. Please consult with @lla-dane in detail as you make improvements.

Antrikshgwal · 2025-09-01T15:43:50Z

@lla-dane

lla-dane · 2025-09-01T16:48:00Z

@Antrikshgwal: Fixed the linter issues in this commit: lla-dane@bcb58ba

seetadev · 2025-09-01T18:25:23Z

@Antrikshgwal : Thank you for the improvements.

Also, thank you @lla-dane for fixing the lint issue.

@lla-dane : Re-ran the CI/CD pipeline. Looks like your changes are yet to be merged.

Looking forward to arriving at a good conclusion on the issue.

@Antrikshgwal : Please add the test suite like the one @lla-dane added for adding signed peer record transfer support in kad-dht and pub-sub/gossipsub. Please consult with @lla-dane in detail as you make improvements. Also, wish to ask if you have added newsfragment file.

lla-dane · 2025-09-11T12:48:32Z

Like both them are just envelope wrapped peer-records only right? When the client contacts the relay, it uses HopMessages and sends its signed peer record in the signedRecord parameter. And when there is communication between relay and destination-peer, the sender includes their signed-record in the senderRecord component. Right ?

I would suggest, at both the places (HopMessage and StopMessage schema), stick to a single name only for the signed-peer-records, preferably senderRecord, for less confusion.

Antrikshgwal · 2025-09-11T12:54:23Z

Like both them are just envelope wrapped peer-records only right? When the client contacts the relay, it uses HopMessages and sends its signed peer record in the signedRecord parameter. And when there is communication between relay and destination-peer, the sender includes their signed-record in the senderRecord component. Right ?

Yeah, makes sense.

Antrikshgwal · 2025-09-11T12:55:54Z

Like both them are just envelope wrapped peer-records only right? When the client contacts the relay, it uses HopMessages and sends its signed peer record in the signedRecord parameter. And when there is communication between relay and destination-peer, the sender includes their signed-record in the senderRecord component. Right ?

I would suggest, at both the places (HopMessage and StopMessage schema), stick to a single name only for the signed-peer-records, preferably senderRecord, for less confusion.

Will do. Thanks for the suggestion.

Antrikshgwal · 2025-09-13T19:22:05Z

In this function:

async def _send_status(
    self,
    stream: ReadWriteCloser,
    code: int,
    message: str,
    envelope: Envelope | None = None,
) -> None:
    """Send a status message."""
    try:
		..
		..
            status_msg = HopMessage(
                type=HopMessage.STATUS,
                status=pb_status,
                signedRecord=envelope,
            )
		..
		..

Envelope parameter is optional, but at all the places where this function is called like this:

await self._send_status(
    stream,
    StatusCode.MALFORMED_MESSAGE,
    f"Invalid message type: {hop_msg.type}",
)

Envelope is not passed, I would suggest passing the envelope param at all the places, since a HopMessage is being sent out via this function.

Added the Envelope parameter in _send_status and _stop_send_status calls with appropiate envelopes

Antrikshgwal · 2025-09-13T19:22:51Z

@Antrikshgwal: There are many places where HopMessages are sent out, but the senderRecord from the sender's side is not included, make sure to include them at all the places, and handle them properly at the receiving end.

added SPR in every HOP and STOP message.

Antrikshgwal · 2025-09-13T19:24:46Z

@Antrikshgwal: There are many places where HopMessages are sent out, but the senderRecord from the sender's side is not included, make sure to include them at all the places, and handle them properly at the receiving end.

Also modified the protobuf schema. Now the record containing field in both HOP and STOP schemas is named senderRecord

Antrikshgwal · 2025-09-13T19:25:52Z

@lla-dane Please let me know if further changes has to be made.

seetadev · 2025-09-15T19:20:31Z

@Antrikshgwal : Great, thank you so much for addressing the feedback by @lla-dane. Appreciate it.

Please add a test suite and newsfragment too.

seetadev · 2025-09-21T20:26:01Z

@lla-dane and @Antrikshgwal : Please try and complete this important PR before the maintainer's call this week. We plan to do a py-libp2p release once websockets support is added and the corresponding PR merged. Would like your opened PRs to be reviewed, merged and landed in the new release too.

Antrikshgwal · 2025-09-22T05:42:50Z

@lla-dane and @Antrikshgwal : Please try and complete this important PR before the maintainer's call this week. We plan to do a py-libp2p release once websockets support is added and the corresponding PR merged. Would like your opened PRs to be reviewed, merged and landed in the new release too.

Sure, I’m waiting on @lla-dane ’s review before proceeding

lla-dane · 2025-09-22T06:17:59Z

@seetadev @Antrikshgwal: Apologize for the delay on this PR, was engaged in a few other things, will surely post a feedback on this PR today.

lla-dane · 2025-09-22T09:47:17Z

tests/core/relay/test_circuit_v2_protocol.py

+                        peer=client_host.get_id().to_bytes(),
+                        senderRecord=corrupted_env.to_bytes(),  # Invalid SPR


Change this line:

senderRecord=corrupted_env.to_bytes()

to this:

senderRecord=corrupted_env.marshal_envelope()

@Antrikshgwal, make this change the failing test will be resolved.

Changed corrupted_env.to_bytes() to corrupted_env.marshal_envelope().

lla-dane · 2025-09-22T09:48:58Z

@seetadev @Antrikshgwal: Looked through the repo, it is nicely done in all the message transfer interfaces. Make a change comment on one of the failing tests, after that the CI runs will pass.

It would be great if @pacrob could also give it a quick look to see if anything is missing.

seetadev · 2025-09-22T18:38:29Z

@Antrikshgwal : Wish to share that I re-ran the CI/CD pipeline and there were multiple issues.

Wish if you could add @Winter-Soren as a collaborator. He will help you resolve the CI/CD issues that are happening and are yet to be resolved.

@lla-dane will definitely share feedback on the PR once CI/CD issues have been resolved.

@lla-dane : @pacrob , @acul71 & I will be spending time this week on the upcoming release of Py-libp2p. Wish to share that we have tested the py-multiaddr release in multiple PRs in py-libp2p. The new release of both py-cid & py-multiaddr has landed well.

pacrob · 2025-09-22T21:56:44Z

libp2p/relay/circuit_v2/utils.py

+                if not (isinstance(peer_id, ID) and record.peer_id == peer_id):
+                    return False


Here you reject unless peer_id is included, but none of the calls to this function in circuit_v2/protocol.py include an argument for peer_id, causing them all to always return False.

@pacrob Apologies, I added peer id support in the function after using it here and somehow forgot to update these calls. Now the maybe_consume_signed_records calls also send relevant peer ids.

pacrob · 2025-09-22T22:00:54Z

docs/conf.py

 # Prevent autodoc from trying to import module from tests.factories
-autodoc_mock_imports = ["tests.factories"]
+autodoc_mock_imports = ["tests.factories"
+                        "libp2p.relay.circuit_v2.lib"


Why is this needed?

Actually, the Sphinx autodoc was trying to import libp2p.relay.circuit_v2.lib during the docs build, but the module isn’t present in the repo. I have added a comment stating the issue.

pacrob · 2025-09-22T22:18:20Z

libp2p/relay/circuit_v2/transport.py

+            if resp.HasField("senderRecord"):
+                if not maybe_consume_signed_record(resp, self.host, relay_peer_id):
+                    logger.error(
+                        "Received an invalid-signed-record, dropping the stream"


Nit - writing it as "invalid-signed-record" implies there is a variable of that name. Clarify that it's an "invalid senderRecord" or "invalid Signed Peer Record" or something similar. 3 instances in this file and one in discovery.py.

@pacrob Changed invalid-signed-record to invalid senderRecord.

Add SPR field in relayV2 protobuf

c0cadca

Antrikshgwal marked this pull request as draft August 16, 2025 14:44

Merge branch 'main' into SPR-relayV2

634336b

seetadev and others added 3 commits August 17, 2025 17:03

Merge branch 'main' into SPR-relayV2

b330781

Merge branch 'main' into SPR-relayV2

cf1abf6

Add peer records utils

b47f60d

Antrikshgwal marked this pull request as ready for review August 21, 2025 18:41

lla-dane reviewed Aug 23, 2025

View reviewed changes

seetadev and others added 3 commits August 24, 2025 23:01

Merge branch 'main' into SPR-relayV2

9ed718d

Merge branch 'libp2p:main' into SPR-relayV2

bf49de1

Merge branch 'main' into SPR-relayV2

c0e9665

Merge branch 'main' into SPR-relayV2

264d5cd

Downgraded protoc version

4ebe64e

"shift create_signed_records in peerstore"

Antrikshgwal added 2 commits August 31, 2025 19:28

setup SPR handlers

1582644

Fix: type errors in pyi file

a89affd

seetadev and others added 3 commits September 2, 2025 01:01

Merge branch 'main' into SPR-relayV2

60ed38c

Merge branch 'main' into SPR-relayV2

055d46e

Fix docs build error

a8b2bba

Antrikshgwal added 2 commits September 14, 2025 00:26

add spr in all hop messages

2a8a7b5

docs fix

6cfa2eb

Antrikshgwal requested a review from lla-dane September 13, 2025 19:25

Merge branch 'main' into SPR-relayV2

0ee394f

seetadev added 2 commits September 16, 2025 01:03

Merge branch 'main' into SPR-relayV2

ecf6f08

Merge branch 'main' into SPR-relayV2

9c6b24e

Merge branch 'main' into SPR-relayV2

797e881

lla-dane reviewed Sep 22, 2025

View reviewed changes

Merge branch 'main' into SPR-relayV2

9959a42

Merge branch 'main' into SPR-relayV2

022f0cd

pacrob reviewed Sep 22, 2025

View reviewed changes

Fix CI/CD issues

503d4c8

Antrikshgwal requested review from pacrob and lla-dane September 23, 2025 16:00

		peer=client_host.get_id().to_bytes(),
		senderRecord=corrupted_env.to_bytes(), # Invalid SPR

		if not (isinstance(peer_id, ID) and record.peer_id == peer_id):
		return False

Add signed peer record transfer support in circuit-relay V2 protocol. #848

Are you sure you want to change the base?

Add signed peer record transfer support in circuit-relay V2 protocol. #848

Uh oh!

Conversation

Antrikshgwal commented Aug 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What was wrong?

How was it fixed?

To-Do

Cute Animal Picture

Uh oh!

lla-dane commented Aug 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

seetadev commented Aug 17, 2025

Uh oh!

seetadev commented Aug 17, 2025

Uh oh!

Antrikshgwal commented Aug 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seetadev commented Aug 25, 2025

Uh oh!

sumanjeet0012 commented Aug 29, 2025

1. Failing Test Cases

2. Linting Issues

3. Documentation Issue

Uh oh!

Antrikshgwal commented Aug 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

seetadev commented Aug 30, 2025

Uh oh!

Antrikshgwal commented Sep 1, 2025

Uh oh!

lla-dane commented Sep 1, 2025

Uh oh!

seetadev commented Sep 1, 2025

Uh oh!

lla-dane commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Antrikshgwal commented Sep 11, 2025

Uh oh!

Antrikshgwal commented Sep 11, 2025

Uh oh!

Antrikshgwal commented Sep 13, 2025

Uh oh!

Antrikshgwal commented Sep 13, 2025

Uh oh!

Antrikshgwal commented Sep 13, 2025

Uh oh!

Antrikshgwal commented Sep 13, 2025

Uh oh!

seetadev commented Sep 15, 2025

Uh oh!

seetadev commented Sep 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Antrikshgwal commented Sep 22, 2025

Uh oh!

lla-dane commented Sep 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lla-dane commented Sep 22, 2025

Uh oh!

seetadev commented Sep 22, 2025

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

Antrikshgwal commented Aug 16, 2025 •

edited

Loading

lla-dane commented Aug 17, 2025 •

edited

Loading

Antrikshgwal commented Aug 30, 2025 •

edited

Loading

lla-dane commented Sep 11, 2025 •

edited

Loading

seetadev commented Sep 21, 2025 •

edited

Loading

Antrikshgwal Sep 23, 2025 •

edited

Loading