Introduce support for creation and validation of compact, V2-only IPNS Records.
IPNS record creation and validation is overly complex due to the legacy of decisions made in 2021.
The "V1+V2" record creation and validation was reverse-engineered and documented the current state in ipfs/specs#319, which created a base for specifications to improve upon.
A quick refresher on how IPNS Record lifecycle works today (2023 Q2):
Record Creation produces both V1 and V2 signatures, and the record has
duplicated values in both top level protobuf AND
data CBOR field.
Record Validation only cares about V2 signature, but still requires fields
related to V1 to be always present in a record and match values from CBOR in
data field, for the record to be considered valid.
We've been producing and expecting these hybrid V1+V2 records since 2021.
An unfortunate result is that all mandatory values MUST be duplicated, even
when both ends use a modern client that only cares about
guards CBOR field, otherwise the record will not be valid.
What this IPIP aims to improve is allow implementations to produce lean, V2-only IPNS records and ensure clients will interpret them as valid IPNS.
Finish V2 story by making V2-Only records possible, namely:
Record Creation: document and default to lean V2-Only records, keep V1+V2 as legacy backward-compatible variant.
Record Validation: adjust the algorithm to stop requiring V1 fields when there is no
For details, see the updated [ipns-record] specification.
For modern IPNS, the outer
IpnsEntry protobuf should effectively only have
two required fields:
data and its
signatureV2, and such record, as long
signature is valid, should be accepted as valid.
At the same time, we don't want to break existig software, especially software and hardware devices which use IPNS for pulling updates.
We can get to that future in two steps:
Reference implementations (boxo/ipns, js-ipns) will keep producing V1+V2 records as backward-compatible default, but we adjust validation algorithm to allow V2-only records, and support creation of such records as opt-in in modern implementations of IPFS+IPNS, like Kubo (GO) and Helia (JS).
signatureV1is present in the
signatureV1, the V1 record would be invalid anyway.
datafields are present and valid, the V2-only record should be considered valid.
At some point in the future, e.g. when we see the majority of the public swarm supports V2-Only records, libraries like boxo/ipns, js-ipns and implementations like Kubo will stop producing V1+V2 and switch to publishing V2-only records that are protobuf with only two fields: Data CBOR+signatureV2.
End users: the main benefit for end user is the smaller size of IPNS Records and less complexity during creation/validation of modern V2-only records.
Developers interested in IPNS: by making IPNS Record creation as simple as "create DAG-CBOR with these fields, and sign it", and validation to "signatureV2 should match the DAG-CBOR value and key". We've removed surface for bugs, making it easier to reason about for use in greenfield projects.
IPFS ecosystem: lowering the complexity related to IPNS record creation and validation makes it more likely for third-party interoperable IPNS implementations to happen.
This is backward-compatible, we adjust validation logic to allow V2-only records, but all V1+V2 records that are being used in the wild today are still valid
V2-only rollout is not part of this IPIP.
Our suggestion is to default to creating V1+V2 records for now, keeping backward-compatibility with the old IPNS clients.
Creation of V2-only records should be introduced as an explicit opt-in. It is up to implementations to decide when it is feasible to default to creating V2-only records on IPNS publish.
IpnsEntry.signatureV1(protobuf field) is parsed only by legacy clients, modern ones ignore this value
It is highly advised to implement validation conformance tests using the fixtures included at the end of this IPIP.
Describe alternate designs that were considered and related work.
Just switch to V2-only as the new default!
signatureV1is missing. So technically there was never "V2", it was more like "V1.5". Only with this IPIP, we finally adjust validation to only care about CBOR values when there is no
Why keeping the outer protobuf envelope? Could we make IPNS DAG-CBOR-only?
To make testing easier below are test vectors in form of IPNS records along with the expected verification results. These test records are valid for 100 years, making them safe for use in CI tests.
Copyright and related rights waived via CC0.