Skip to content

Conversation

@cong-or
Copy link
Contributor

@cong-or cong-or commented Dec 10, 2025

Add with_keypair() Method to HermesIpfsBuilder for Persistent Keypair Support

Summary

This PR adds a with_keypair() method to HermesIpfsBuilder that enables creating an IPFS
node builder with an existing keypair instead of auto-generating a new one. This is
essential for supporting persistent peer identities across node restarts.

Motivation

Currently, hermes-ipfs only exposes HermesIpfsBuilder::new(), which auto-generates a new
keypair on each instantiation. While the underlying rust_ipfs::IpfsBuilder supports
creating builders with existing keypairs via IpfsBuilder::with_keypair(), this
functionality was not exposed through the hermes-ipfs API.

Without this capability, applications cannot:

  • Maintain stable peer IDs across restarts
  • Load keypairs from persistent storage
  • Use deterministic peer identities for testing or deployment

Changes

Added HermesIpfsBuilder::with_keypair() method

pub fn with_keypair(keypair: impl connexa::builder::IntoKeypair) ->
    std::io::Result<Self>
  • Accepts any type implementing connexa::builder::IntoKeypair (including
    libp2p::identity::Keypair)
  • Wraps the underlying IpfsBuilder::with_keypair() method

Usage Example

use hermes_ipfs::HermesIpfsBuilder;
use libp2p::identity::Keypair;

// Load a keypair from disk (or generate and save)
let keypair = load_or_create_keypair("path/to/keypair.key")?;

// Create builder with the persistent keypair
let node = HermesIpfsBuilder::with_keypair(keypair)?
    .with_default()
    .set_default_listener()
    .enable_tcp()
    .enable_quic()
    .enable_dns()
    .start()
    .await?;

// Node will now have the same peer ID on every restart

…r support

  This adds a  method to  that allows
  creating an IPFS node builder with an existing keypair instead of
  generating a new one. This enables stable peer IDs across restarts
  when keypairs are loaded from disk.

  The method wraps  and follows the same
  Add  method to HermesIpfsBuilder that configures
  Gossipsub with mesh parameters suitable for 2-3 node test networks:
  - mesh_n_low: 1 (minimum peers)
  - mesh_n: 2 (target peers)
  - mesh_n_high: 3 (maximum peers)
  - mesh_outbound_min: 1

  Default Gossipsub configuration expects mesh_n=6 peers, which doesn't work
  in small test environments. This method provides an alternative to
   for testing scenarios.

  Use via environment variable HERMES_P2P_TEST_MODE=true to enable small mesh
  configuration automatically.
@cong-or cong-or added the squad: hermetics Hermes Backend, System Development & Integration Team label Dec 10, 2025
@cong-or cong-or added this to Catalyst Dec 10, 2025
@cong-or cong-or moved this from New to 👀 In review in Catalyst Dec 10, 2025
@cong-or cong-or marked this pull request as ready for review December 10, 2025 00:25
@cong-or cong-or changed the title feat(rust/hermes-ipfs): iipfs persistent keypair feat(rust/hermes-ipfs): ipfs persistent keypair Dec 10, 2025
@cong-or cong-or enabled auto-merge (squash) December 10, 2025 00:27
@github-actions
Copy link
Contributor

📚 Docs Preview

The docs for this PR can be previewed at the following URL:

https://docs.dev.projectcatalyst.io/libs/feat/hermes-ipfs-persistent-keypair

@github-actions
Copy link
Contributor

github-actions bot commented Dec 10, 2025

Test Report | ${\color{lightgreen}Pass: 605/605}$ | ${\color{red}Fail: 0/605}$ |

Copy link
Contributor

@rafal-ch rafal-ch left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍

@cong-or cong-or merged commit 4257225 into main Dec 10, 2025
23 checks passed
@cong-or cong-or deleted the feat/hermes-ipfs-persistent-keypair branch December 10, 2025 10:12
@github-project-automation github-project-automation bot moved this from 👀 In review to ✅ Done in Catalyst Dec 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

squad: hermetics Hermes Backend, System Development & Integration Team

Projects

Status: ✅ Done

Development

Successfully merging this pull request may close these issues.

3 participants