Skip to content

chore: Fill in todos #172

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

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

chore: Fill in todos #172

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0e19788
Fill in todos
MarcoPolo Jun 5, 2024
759089b
Update README.md
MarcoPolo Jun 6, 2025
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
50 changes: 36 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,18 @@

> Composable and future-proof network addresses

- [Introduction](#introduction)
- [Use cases](#use-cases)
- [Encapsulation based on context](#encapsulation-based-on-context)
- [Specification](#specification)
- [Encoding](#encoding)
- [Decoding](#decoding)
- [Protocols](#protocols)
- [Implementations](#implementations)
- [Contribute](#contribute)
- [License](#license)
- [multiaddr](#multiaddr)
- [Introduction](#introduction)
- [Interpreting multiaddrs](#interpreting-multiaddrs)
- [Use cases](#use-cases)
- [Encapsulation based on context](#encapsulation-based-on-context)
- [Specification](#specification)
- [Encoding (Bytes -\> String)](#encoding-bytes---string)
- [Decoding (String -\> Bytes)](#decoding-string---bytes)
- [Protocols](#protocols)
- [Implementations](#implementations)
- [Contribute](#contribute)
- [License](#license)


## Introduction
Expand Down Expand Up @@ -132,13 +134,33 @@ Multiaddr and all other multiformats use unsigned varints (uvarint).
Read more about it in [multiformats/unsigned-varint](https://github.com/multiformats/unsigned-varint).


### Encoding
### Encoding (Bytes -> String)
Copy link
Member

Choose a reason for hiding this comment

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

I know this has been in the spec for like, ever, but is this the right way round? IPLD generally refers to "encoding" as turning an object (string, here) into bytes and "decoding" as getting an object from bytes.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

wdyt about String Encoding instead?

Copy link
Member

Choose a reason for hiding this comment

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

I think it has the same problem since "encoding" is still in the title.

This README was written a long time ago and the ecosystem has coalesced around certain language and conventions since then, I think we should bring this in line with everything else.


TODO: specify the encoding (byte-array to string) procedure
1. Varint-decode the first byte(s) and find the corresponding protocol.
2. Read bytes that follow according to the rules defined by that protocol. This is the value for that protocol.
1. Generally this will be a fixed number of bytes, or
2. a varint length prefixed number of bytes.
3. Some protocols have no value. This is equivalent to 0 bytes.
3. The protocol + value combination is a component.
4. Repeat for the remaining bytes to gather all the components.
5. For each component create the string `/<protocol-name>/<protocol-value>` where protocol-value is the string form of the component's bytes as defined by that protocol.
1. If the component has no value, the string is `/<protocol-name>`
6. Join all the strings together.

### Decoding
### Decoding (String -> Bytes)

TODO: specify the decoding (string to byte-array) procedure
Given a multiaddr string and an output byte buffer.

1. Discard the leading `/`.
2. Parse the protocol from the name until the next `/`.
3. Push the protocol's varint-encoded code to the byte buffer.
4. If the protocol has a value:
1. Read the value by reading the next part of the string until the next `/`.
2. Convert this value into bytes per the rules of the protocol.
3. Append these bytes to the byte buffer
5. Repeat until you reach the end of the string

The byte buffer will contain the machine-readable form of the multiaddr.


## Protocols
Expand Down