Skip to content

chore(docs): move documentation files to docs folder #2052

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chaitanyaprem merged 2 commits into from
Jan 28, 2026
Merged

chore(docs): move documentation files to docs folder #2052

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7d4e66a
chore: move all docs to docs folder
chaitanyaprem Jan 27, 2026
d462b09
updated as per review comments
chaitanyaprem Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 44 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
</p>

## Background

libp2p is a [Peer-to-Peer](https://en.wikipedia.org/wiki/Peer-to-peer) networking stack, with [implementations](https://github.com/libp2p/libp2p#implementations) in multiple languages derived from the same [specifications.](https://github.com/libp2p/specs)

Building large scale peer-to-peer systems has been complex and difficult in the last 15 years and libp2p is a way to fix that. It strives to be a modular stack with secure defaults and useful protocols, while remaining open and extensible.
Expand All @@ -27,7 +28,7 @@ Learn more about libp2p at [**libp2p.io**](https://libp2p.io) and follow libp2p'

nim-libp2p is a great place to contribute. Your contribution will help drive thousands of decentralized nodes across networks worldwide.

The best part is that nim-libp2p has **good first issues** that are especially suited for newcomers. Your contributions will be guided by core maintainers, just like an **internship expiriance** but decentralized.
The best part is that nim-libp2p has **good first issues** that are especially suited for newcomers. Your contributions will be guided by core maintainers, just like an **internship experience** but decentralized.

Jump into the [contributing](docs/contributing.md) page to get started, `nim-libp2p` is expecting your contribution!

Expand All @@ -38,16 +39,13 @@ The currently supported Nim versions are v2.0.16 and v2.2.6.
```
nimble install libp2p
```

You'll find the nim-libp2p documentation [here](https://vacp2p.github.io/nim-libp2p/docs/). See [examples](./examples) for simple usage patterns.

## Development

Read the [development guide](docs/development.md) to get started with the project and testing.

Additional resources:

- [Compile time flags](docs/compile_time_flags.md) - all available compile-time options
- [Common hurdles](docs/common_hurdles.md) - frequently encountered issues and solutions
See the [development guide](docs/development.md) to get started with the project and testing.
For more details, refer to the [documentation](docs/README.md).

## Contributors

Expand All @@ -62,65 +60,68 @@ Connect with other contributors in our [community channel](https://discord.com/c
## Users

nim-libp2p is used by:

- [Nimbus](https://github.com/status-im/nimbus-eth2), an Ethereum client
- [nwaku](https://github.com/waku-org/nwaku), a decentralized messaging application
- [nim-codex](https://github.com/codex-storage/nim-codex), a decentralized storage application
- (open a pull request if you want to be included here)

## Stability

nim-libp2p has been used in production for many years in high-stake scenarios, so its core is considered stable.
Some modules are more recent and less stable.

The versioning follows [semver](https://semver.org/), with some additions:

- Some of libp2p procedures are marked as `.public.`, they will remain compatible during each `MAJOR` version
- The rest of the procedures are considered internal, and can change at any `MINOR` version (but remain compatible for each new `PATCH`)

## License

Licensed and distributed under either of

* MIT license: [LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT
- MIT license: [LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT

or

* Apache License, Version 2.0, ([LICENSE-APACHEv2](LICENSE-APACHEv2) or http://www.apache.org/licenses/LICENSE-2.0)
- Apache License, Version 2.0, ([LICENSE-APACHEv2](LICENSE-APACHEv2) or http://www.apache.org/licenses/LICENSE-2.0)

at your option. These files may not be copied, modified, or distributed except according to those terms.


## Modules

List of packages modules implemented in nim-libp2p:

| Name | Description |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Libp2p** | |
| [libp2p](libp2p/switch.nim) | The core of the project |
| [connmanager](libp2p/connmanager.nim) | Connection manager |
| [identify / push identify](libp2p/protocols/identify.nim) | [Identify](https://docs.libp2p.io/concepts/fundamentals/protocols/#identify) protocol |
| [ping](libp2p/protocols/ping.nim) | [Ping](https://docs.libp2p.io/concepts/fundamentals/protocols/#ping) protocol |
| **Transports** | |
| [libp2p-tcp](libp2p/transports/tcptransport.nim) | TCP transport |
| [libp2p-ws](libp2p/transports/wstransport.nim) | WebSocket & WebSocket Secure transport |
| [libp2p-tor](libp2p/transports/tortransport.nim) | Tor Transport |
| [libp2p-quic](libp2p/transports/quictransport.nim) | Quic Transport |
| [libp2p-memory](libp2p/transports/memorytransport.nim) | Memory Transport |
| **Secure Channels** | |
| [libp2p-noise](libp2p/protocols/secure/noise.nim) | [Noise](https://docs.libp2p.io/concepts/secure-comm/noise/) secure channel |
| [libp2p-plaintext](libp2p/protocols/secure/plaintext.nim) | Plain Text for development purposes |
| **Stream Multiplexers** | |
| [libp2p-mplex](libp2p/muxers/mplex/mplex.nim) | [MPlex](https://github.com/libp2p/specs/tree/master/mplex) multiplexer |
| [libp2p-yamux](libp2p/muxers/yamux/yamux.nim) | [Yamux](https://docs.libp2p.io/concepts/multiplex/yamux/) multiplexer |
| **Data Types** | |
| [peer-id](libp2p/peerid.nim) | [Cryptographic identifiers](https://docs.libp2p.io/concepts/fundamentals/peers/#peer-id) |
| [peer-store](libp2p/peerstore.nim) | [Address book of known peers](https://docs.libp2p.io/concepts/fundamentals/peers/#peer-store) |
| [multiaddress](libp2p/multiaddress.nim) | [Composable network addresses](https://github.com/multiformats/multiaddr) |
| [signed-envelope](libp2p/signed_envelope.nim) | [Signed generic data container](https://github.com/libp2p/specs/blob/master/RFC/0002-signed-envelopes.md) |
| [routing-record](libp2p/routing_record.nim) | [Signed peer dialing informations](https://github.com/libp2p/specs/blob/master/RFC/0003-routing-records.md) |
| [discovery manager](libp2p/discovery/discoverymngr.nim) | Discovery Manager |
| **Utilities** | |
| [libp2p-crypto](libp2p/crypto) | Cryptographic backend |
| [libp2p-crypto-secp256k1](libp2p/crypto/secp.nim) | |
| **Pubsub** | |
| [libp2p-pubsub](libp2p/protocols/pubsub/pubsub.nim) | Pub-Sub generic interface |
| [libp2p-floodsub](libp2p/protocols/pubsub/floodsub.nim) | FloodSub implementation |
| [libp2p-gossipsub](libp2p/protocols/pubsub/gossipsub.nim) | [GossipSub](https://docs.libp2p.io/concepts/publish-subscribe/) implementation |
| Name | Description |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Libp2p** | |
| [libp2p](libp2p/switch.nim) | The core of the project |
| [connmanager](libp2p/connmanager.nim) | Connection manager |
| [identify / push identify](libp2p/protocols/identify.nim) | [Identify](https://docs.libp2p.io/concepts/fundamentals/protocols/#identify) protocol |
| [ping](libp2p/protocols/ping.nim) | [Ping](https://docs.libp2p.io/concepts/fundamentals/protocols/#ping) protocol |
| **Transports** | |
| [libp2p-tcp](libp2p/transports/tcptransport.nim) | TCP transport |
| [libp2p-ws](libp2p/transports/wstransport.nim) | WebSocket & WebSocket Secure transport |
| [libp2p-tor](libp2p/transports/tortransport.nim) | Tor Transport |
| [libp2p-quic](libp2p/transports/quictransport.nim) | Quic Transport |
| [libp2p-memory](libp2p/transports/memorytransport.nim) | Memory Transport |
| **Secure Channels** | |
| [libp2p-noise](libp2p/protocols/secure/noise.nim) | [Noise](https://docs.libp2p.io/concepts/secure-comm/noise/) secure channel |
| [libp2p-plaintext](libp2p/protocols/secure/plaintext.nim) | Plain Text for development purposes |
| **Stream Multiplexers** | |
| [libp2p-mplex](libp2p/muxers/mplex/mplex.nim) | [MPlex](https://github.com/libp2p/specs/tree/master/mplex) multiplexer |
| [libp2p-yamux](libp2p/muxers/yamux/yamux.nim) | [Yamux](https://docs.libp2p.io/concepts/multiplex/yamux/) multiplexer |
| **Data Types** | |
| [peer-id](libp2p/peerid.nim) | [Cryptographic identifiers](https://docs.libp2p.io/concepts/fundamentals/peers/#peer-id) |
| [peer-store](libp2p/peerstore.nim) | [Address book of known peers](https://docs.libp2p.io/concepts/fundamentals/peers/#peer-store) |
| [multiaddress](libp2p/multiaddress.nim) | [Composable network addresses](https://github.com/multiformats/multiaddr) |
| [signed-envelope](libp2p/signed_envelope.nim) | [Signed generic data container](https://github.com/libp2p/specs/blob/master/RFC/0002-signed-envelopes.md) |
| [routing-record](libp2p/routing_record.nim) | [Signed peer dialing information](https://github.com/libp2p/specs/blob/master/RFC/0003-routing-records.md) |
| [discovery manager](libp2p/discovery/discoverymngr.nim) | Discovery Manager |
| **Utilities** | |
| [libp2p-crypto](libp2p/crypto) | Cryptographic backend |
| [libp2p-crypto-secp256k1](libp2p/crypto/secp.nim) | |
| **Pubsub** | |
| [libp2p-pubsub](libp2p/protocols/pubsub/pubsub.nim) | Pub-Sub generic interface |
| [libp2p-floodsub](libp2p/protocols/pubsub/floodsub.nim) | FloodSub implementation |
| [libp2p-gossipsub](libp2p/protocols/pubsub/gossipsub.nim) | [GossipSub](https://docs.libp2p.io/concepts/publish-subscribe/) implementation |
18 changes: 18 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Documentation Index

Welcome to the nim-libp2p documentation. Use the links below to navigate:

## Guides

- [Development Guide](development.md)
- [Common Hurdles](common_hurdles.md)
- [Contributing](contributing.md)
- [Compile Time Flags](compile_time_flags.md)
- Protocols
- [Mix Protocol](protocols_mix.md)
- [Spam Protection](protocols_mix_spam_protection.md)
- [Hole Punching Interop](interop_hole_punching.md)

---

[← Back to README](../README.md)
18 changes: 10 additions & 8 deletions docs/common_hurdles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Common hurdles

This page will document all common hurdles you may expiriance while developing or using nim-libp2p.
This page will document all common hurdles you may experience while developing or using nim-libp2p.

## compile error: undeclared identifier

Sometimes compiling nim-libp2p or your project that deepnds on nim-libp2p may produce following commpile error:
Sometimes compiling nim-libp2p or your project that depends on nim-libp2p may produce the following compile error:

```
nim c -r --threads:on libp2p_chat_example.nim
Expand All @@ -14,17 +14,19 @@ Hint: used config file '/home/user/.choosenim/toolchains/nim-2.2.0/config/config
/home/user/.nimble/pkgs2/libp2p-1.14.3-3c089f3ccd23aa5a04e5db288cb8eef524938487/libp2p/utility.nim(77, 30) Error: undeclared identifier: 'Opt'
```

Error message `Error: undeclared identifier:` can complain about indentifer of any other library - it will be different from time to time. Root cause is the same for all error of this kind.
Error message `Error: undeclared identifier:` can complain about identifier of any other library - it will be different from time to time. Root cause is the same for all errors of this kind.

To fix this please, follow these steps:

1) remove `/home/user/.nimble` - to remove everything (nim & nimble)
2) install nim again - fresh install
3) `nimble install nimble` - get latest `nimble` first
4) then install libp2p
1. remove `/home/user/.nimble` - to remove everything (nim & nimble)
2. install nim again - fresh install
3. `nimble install nimble` - get latest `nimble` first
4. then install libp2p

---

(open a pull request if you want something to be included here)

---

(open a pull request if you want something to be included here)
[← Back to README](../README.md)
24 changes: 17 additions & 7 deletions docs/compile_time_flags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,41 @@
# Compile time flags

Enable autotls support

```bash
nim c -d:libp2p_autotls_support some_file.nim
```

Enable expensive metrics (ie, metrics with per-peer cardinality):

```bash
nim c -d:libp2p_expensive_metrics some_file.nim
```

Set list of known libp2p agents for metrics:

```bash
nim c -d:libp2p_agents_metrics -d:KnownLibP2PAgents=nimbus,lighthouse,lodestar,prysm,teku some_file.nim
```

Specify gossipsub specific topics to measure in the metrics:

```bash
nim c -d:KnownLibP2PTopics=topic1,topic2,topic3 some_file.nim
```

## Flags that extend `MultiFormats`

| Multi format | Compiler flag<br>(path to extensions file) | Expected definition in extension file |
|----------------|--------------------------------------------|-------------------------------|
| `MultiCodec` | `-d:libp2p_multicodec_exts` | `const CodecExts = []` |
| `MultiHash` | `-d:libp2p_multihash_exts` | `const HashExts = []` |
| `MultiAddress` | `-d:libp2p_multiaddress_exts` | `const AddressExts = []` |
| `MultiBase` | `-d:libp2p_multibase_exts` | `const BaseExts = []` |
| `ContentIds` | `-d:libp2p_contentids_exts` | `const ContentIdsExts = []` |
| -------------- | ------------------------------------------ | ------------------------------------- |
| `MultiCodec` | `-d:libp2p_multicodec_exts` | `const CodecExts = []` |
| `MultiHash` | `-d:libp2p_multihash_exts` | `const HashExts = []` |
| `MultiAddress` | `-d:libp2p_multiaddress_exts` | `const AddressExts = []` |
| `MultiBase` | `-d:libp2p_multibase_exts` | `const BaseExts = []` |
| `ContentIds` | `-d:libp2p_contentids_exts` | `const ContentIdsExts = []` |

For example, a file called `multihash_exts.nim` could be created and contain `MultiHash` extensions:

```nim
proc coder1(data: openArray[byte], output: var openArray[byte]) =
copyMem(addr output[0], unsafeAddr data[0], len(output))
Expand All @@ -47,4 +52,9 @@ const HashExts = [
MHash(mcodec: multiCodec("sha2-256"), size: 6, coder: sha2_256_override),
]
```
These `MultiHashes` will be available at compile time when the binary is compiled with `-d:libp2p_multihash_exts=multihash_exts.nim`.

These `MultiHashes` will be available at compile time when the binary is compiled with `-d:libp2p_multihash_exts=multihash_exts.nim`.

---

[← Back to README](../README.md)
Loading
Loading