From baaf8240a29fb69077f61d683471ca7efb29ba1d Mon Sep 17 00:00:00 2001 From: Bryan White Date: Fri, 14 Apr 2023 13:22:31 +0200 Subject: [PATCH 1/5] docs: add ADR0001 --- ADRs/0001-adopt-multiaddr.md | 60 ++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 ADRs/0001-adopt-multiaddr.md diff --git a/ADRs/0001-adopt-multiaddr.md b/ADRs/0001-adopt-multiaddr.md new file mode 100644 index 0000000..e1a6e58 --- /dev/null +++ b/ADRs/0001-adopt-multiaddr.md @@ -0,0 +1,60 @@ +# ADR-0001: Adopt Multiaddr + +# Adopt Multiaddr for Addressing and Protocol Handling + +* Status: draft +* Deciders: Pocket Network team +* Date: 2023-04-17 + +Technical Story: GitHub discussion [#616: Should we go multiaddr](https://github.com/pokt-network/pocket/discussions/616) + +## Context and Problem Statement + +In the context of simplifying and consolidating node identity, facing the need for a standardized and extensible address format, we decided to adopt multiaddr and neglect alternative address conventions, to achieve a future-proof and composable addressing scheme, accepting the additional dependency and learning curve, because multiaddr provides a standard solution with many benefits. + +## Decision Drivers + +* Standardized serialization format +* Supporting arbitrarily deeply nested protocols +* Supporting arbitrary protocol values, i.e., extensible + +## Considered Options + +* Adopting multiaddr +* Custom address convention + +## Decision Outcome + +Chosen option: "Adopting multiaddr", because it provides a standardized, extensible, and future-proof solution for addressing nodes. + +### Positive Consequences + +* Standardized and easily parsable node addresses +* Extensible and composable address format +* Future-proof addressing scheme + +### Negative Consequences + +* Additional dependency on the multiaddr library +* Learning curve for understanding multiaddr abstraction + +## Pros and Cons of the Options + +### Adopting multiaddr + +* Good, because it provides a standardized and extensible address format +* Good, because it supports arbitrarily deeply nested protocols +* Good, because it is a widely adopted solution in the p2p ecosystem +* Bad, because it introduces an additional dependency +* Bad, because it requires learning a new abstraction + +### Custom address convention + +* Good, because it doesn't require an additional dependency +* Bad, because it may lead to a non-standard and less extensible solution +* Bad, because it requires development and maintenance efforts + +### Links + +* [`go-multiaddr` GitHub repo](https://github.com/multiformats/go-multiaddr) +* [`multiaddr` specification](https://github.com/multiformats/multiaddr) From 5dbf590f8b953443d9091af91db620e05e28b316 Mon Sep 17 00:00:00 2001 From: Bryan White Date: Fri, 21 Apr 2023 09:12:47 +0200 Subject: [PATCH 2/5] ADR0001: status "in review" --- ADRs/0001-adopt-multiaddr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ADRs/0001-adopt-multiaddr.md b/ADRs/0001-adopt-multiaddr.md index e1a6e58..af041e3 100644 --- a/ADRs/0001-adopt-multiaddr.md +++ b/ADRs/0001-adopt-multiaddr.md @@ -2,7 +2,7 @@ # Adopt Multiaddr for Addressing and Protocol Handling -* Status: draft +* Status: in review * Deciders: Pocket Network team * Date: 2023-04-17 From d54250ba7aaac132f6550ddb36ee9cc500d4cbce Mon Sep 17 00:00:00 2001 From: Bryan White Date: Fri, 28 Apr 2023 11:22:07 +0200 Subject: [PATCH 3/5] refactor: reformat using udpated template (#40) --- ADRs/0001-adopt-multiaddr.md | 92 +++++++++++++++++++++++------------- 1 file changed, 58 insertions(+), 34 deletions(-) diff --git a/ADRs/0001-adopt-multiaddr.md b/ADRs/0001-adopt-multiaddr.md index af041e3..3361011 100644 --- a/ADRs/0001-adopt-multiaddr.md +++ b/ADRs/0001-adopt-multiaddr.md @@ -1,60 +1,84 @@ -# ADR-0001: Adopt Multiaddr +# ADR-0001: Adopt Multiaddr -# Adopt Multiaddr for Addressing and Protocol Handling +- Status: in review +- Deciders: Pocket Network team +- Date: 2023-04-17 -* Status: in review -* Deciders: Pocket Network team -* Date: 2023-04-17 +**Table of Contents** -Technical Story: GitHub discussion [#616: Should we go multiaddr](https://github.com/pokt-network/pocket/discussions/616) +- [Problem Statement](#problem-statement-) +- [Technical Story](#technical-story-) +- [Decision Drivers](#decision-drivers-) +- [Considered Options](#considered-options-) +- [Decision Outcome](#decision-outcome-) + - [Positive Consequences](#positive-consequences-) + - [Negative Consequences](#negative-consequences-) +- [Pros and Cons of the Options](#pros-and-cons-of-the-options-) + - [Adopting multiaddr](#adopting-multiaddr) + - [Custom address convention](#custom-address-convention) +- [References](#references-) -## Context and Problem Statement +## Problem Statement In the context of simplifying and consolidating node identity, facing the need for a standardized and extensible address format, we decided to adopt multiaddr and neglect alternative address conventions, to achieve a future-proof and composable addressing scheme, accepting the additional dependency and learning curve, because multiaddr provides a standard solution with many benefits. -## Decision Drivers +## Technical Story -* Standardized serialization format -* Supporting arbitrarily deeply nested protocols -* Supporting arbitrary protocol values, i.e., extensible +[GitHub discussion #616: Should we go multiaddr](https://github.com/pokt-network/pocket/discussions/616) -## Considered Options +## Decision Drivers -* Adopting multiaddr -* Custom address convention +- Standardized serialization format +- Supporting arbitrarily deeply nested protocols +- Supporting arbitrary protocol values, i.e., extensible -## Decision Outcome +## Considered Options + +1. Adopting multiaddr +2. Custom address convention + +## Decision Outcome Chosen option: "Adopting multiaddr", because it provides a standardized, extensible, and future-proof solution for addressing nodes. -### Positive Consequences +### Positive Consequences -* Standardized and easily parsable node addresses -* Extensible and composable address format -* Future-proof addressing scheme +- Standardized and easily parsable node addresses +- Extensible and composable address format +- Future-proof addressing scheme -### Negative Consequences +### Negative Consequences -* Additional dependency on the multiaddr library -* Learning curve for understanding multiaddr abstraction +- Additional dependency on the multiaddr library +- Learning curve for understanding multiaddr abstraction -## Pros and Cons of the Options +## Pros and Cons of the Options ### Adopting multiaddr -* Good, because it provides a standardized and extensible address format -* Good, because it supports arbitrarily deeply nested protocols -* Good, because it is a widely adopted solution in the p2p ecosystem -* Bad, because it introduces an additional dependency -* Bad, because it requires learning a new abstraction +Pros: + +- Provides a standardized and extensible address format +- Supports arbitrarily deeply nested protocols +- Widely adopted solution in the p2p ecosystem + +Cons: + +- Introduces an additional dependency +- Requires learning a new abstraction ### Custom address convention -* Good, because it doesn't require an additional dependency -* Bad, because it may lead to a non-standard and less extensible solution -* Bad, because it requires development and maintenance efforts +Pros: + +- Doesn't require an additional dependency + +Cons: + +- May lead to a non-standard and less extensible solution +- Requires development and maintenance efforts -### Links +## References -* [`go-multiaddr` GitHub repo](https://github.com/multiformats/go-multiaddr) -* [`multiaddr` specification](https://github.com/multiformats/multiaddr) +- [`go-multiaddr` GitHub repo](https://github.com/multiformats/go-multiaddr) +- [`multiaddr` specification](https://github.com/multiformats/multiaddr) \ No newline at end of file From 8758154dda3029f7791027b7cf805db44e0c2dd1 Mon Sep 17 00:00:00 2001 From: Bryan White Date: Fri, 19 May 2023 15:15:22 +0200 Subject: [PATCH 4/5] chore: incorporate updated template & review feedback --- ADRs/0001-adopt-multiaddr.md | 85 +++++++++++++++++++----------------- 1 file changed, 46 insertions(+), 39 deletions(-) diff --git a/ADRs/0001-adopt-multiaddr.md b/ADRs/0001-adopt-multiaddr.md index 3361011..6beae09 100644 --- a/ADRs/0001-adopt-multiaddr.md +++ b/ADRs/0001-adopt-multiaddr.md @@ -1,84 +1,91 @@ # ADR-0001: Adopt Multiaddr - Status: in review -- Deciders: Pocket Network team +- Deciders: Pocket Network Protocol Team - Date: 2023-04-17 **Table of Contents** -- [Problem Statement](#problem-statement-) -- [Technical Story](#technical-story-) -- [Decision Drivers](#decision-drivers-) -- [Considered Options](#considered-options-) -- [Decision Outcome](#decision-outcome-) - - [Positive Consequences](#positive-consequences-) - - [Negative Consequences](#negative-consequences-) -- [Pros and Cons of the Options](#pros-and-cons-of-the-options-) - - [Adopting multiaddr](#adopting-multiaddr) - - [Custom address convention](#custom-address-convention) -- [References](#references-) +- [Summary](#summary) +- [Problem Statement](#problem-statement) +- [Technical Story](#technical-story) +- [Decision Drivers](#decision-drivers) +- [Considered Options](#considered-options) +- [Decision Outcome](#decision-outcome) + - [Positive Consequences](#positive-consequences) + - [Negative Consequences](#negative-consequences) +- [Pros and Cons of the Options](#pros-and-cons-of-the-options) + - [Adopting multiaddr](#adopting-multiaddr) + - [Custom address convention](#custom-address-convention) +- [References](#references) -## Problem Statement +## Summary -In the context of simplifying and consolidating node identity, facing the need for a standardized and extensible address format, we decided to adopt multiaddr and neglect alternative address conventions, to achieve a future-proof and composable addressing scheme, accepting the additional dependency and learning curve, because multiaddr provides a standard solution with many benefits. +In the context of simplifying and consolidating node identity, facing the need for a standardized and extensible address format, we decided for adopting multiaddr and neglected a custom address convention, to achieve a future-proof and composable addressing scheme, accepting the additional dependency and learning curve, because multiaddr provides a standard solution with many benefits. -## Technical Story +## Problem Statement -[GitHub discussion #616: Should we go multiaddr](https://github.com/pokt-network/pocket/discussions/616) +The current addressing system for node identity lacks standardization and extensibility, creating a demand for a unified and future-proof format. -## Decision Drivers +## Background -- Standardized serialization format -- Supporting arbitrarily deeply nested protocols -- Supporting arbitrary protocol values, i.e., extensible +A GitHub discussion was initiated to decide on the direction of the address convention for the Pocket Network nodes: [discussion #616: Should we go multiaddr](https://github.com/pokt-network/pocket/discussions/616). -## Considered Options +## Decision Drivers + +- Need for a standardized serialization format +- Requirement for supporting arbitrarily deeply nested protocols +- Demand for supporting arbitrary protocol values, i.e., extensibility +- Confirming and following the newest & best standards in the industry +- Maintenance by the core team + +## Considered Options 1. Adopting multiaddr 2. Custom address convention -## Decision Outcome +## Decision Outcome -Chosen option: "Adopting multiaddr", because it provides a standardized, extensible, and future-proof solution for addressing nodes. +Chosen option: 1, because it provides a standardized, extensible, and future-proof solution for addressing nodes, while also being widely accepted in the peer-to-peer ecosystem. -### Positive Consequences +### Positive Consequences -- Standardized and easily parsable node addresses -- Extensible and composable address format -- Future-proof addressing scheme +- Implementation of standardized and easily parsable node addresses +- Provision of an extensible and composable address format +- Assurance of a future-proof addressing scheme -### Negative Consequences +### Negative Consequences -- Additional dependency on the multiaddr library -- Learning curve for understanding multiaddr abstraction +- Inclusion of an additional dependency on the multiaddr library +- Necessity for understanding the new abstraction of multiaddr -## Pros and Cons of the Options +## Pros and Cons of the Options ### Adopting multiaddr Pros: -- Provides a standardized and extensible address format +- Offers a standardized and extensible address format - Supports arbitrarily deeply nested protocols -- Widely adopted solution in the p2p ecosystem +- Is a widely adopted solution in the p2p ecosystem Cons: -- Introduces an additional dependency -- Requires learning a new abstraction +- Brings in an additional dependency +- Demands learning a new abstraction ### Custom address convention Pros: -- Doesn't require an additional dependency +- Avoids the need for an additional dependency Cons: -- May lead to a non-standard and less extensible solution +- Could lead to a non-standard and less extensible solution - Requires development and maintenance efforts -## References +## References - [`go-multiaddr` GitHub repo](https://github.com/multiformats/go-multiaddr) -- [`multiaddr` specification](https://github.com/multiformats/multiaddr) \ No newline at end of file +- [`multiaddr` specification](https://github.com/multiformats/multiaddr) From c09e7676f12902dce270b405dbc7b95f3f92be07 Mon Sep 17 00:00:00 2001 From: Bryan White Date: Fri, 26 May 2023 13:54:05 +0200 Subject: [PATCH 5/5] edit: adding detail Co-authored-by: Daniel Olshansky --- ADRs/0001-adopt-multiaddr.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/ADRs/0001-adopt-multiaddr.md b/ADRs/0001-adopt-multiaddr.md index 6beae09..57a9610 100644 --- a/ADRs/0001-adopt-multiaddr.md +++ b/ADRs/0001-adopt-multiaddr.md @@ -38,6 +38,7 @@ A GitHub discussion was initiated to decide on the direction of the address conv - Demand for supporting arbitrary protocol values, i.e., extensibility - Confirming and following the newest & best standards in the industry - Maintenance by the core team +- Backwards compatibility or parity with V0 ## Considered Options @@ -72,13 +73,14 @@ Pros: Cons: - Brings in an additional dependency -- Demands learning a new abstraction +- Demands learning a new abstraction by the core team and community ### Custom address convention Pros: - Avoids the need for an additional dependency +- Lack of need to educate and inform the community of changes Cons: