NFD

# NDN Packet Format v0.3 Transition Plan

This page documents how to adopt NDN Packet Format v0.3 in the implementation. This page shall be updated to indicate implementation progress.

## 3-to-2 Interpretation

In this step, NDN entities (forwarders and libraries) shall be able to receive v0.3 packets. A received v0.3 packet is interpreted as the closest v0.2 packet. Specifically:

* Typed name components are inserted into v0.2 Name or FinalBlockId element. This could cause packet drops in v0.2-only node, but since they are not exposed to applications, there won't be many such packets.

* Interest sub-elements are rearranged into v0.2 order.

* CanBePrefix=0 is converted to MaxSuffixComponents=1; this is set only if the decoder can conclusively identify the Interest packet as v0.3

* If Nonce is omitted, a random nonce is added automatically.

* HopLimit and Parameters are ignored.

* If MetaInfo or Content is omitted, an empty element is added automatically. This breaks signature but permits transport.

Packets shall be encoded as v0.2 format and processed with v0.2 semantics.

Received v0.3 packets may be forwarded as-is and re-encoding is not required (but permitted).

Library APIs shall allow applications to access CanBePrefix and MustBeFresh elements, which will be mapped into their v0.2 counterparts. Functions that depend on v0.2-only elements are deprecated. Typed name components, HopLimit, and Parameters are not yet exposed to applications (they may appear in the library but are not recommended for application use).

This step prepares NDN entities so that they can receive v0.3 packets. It is backwards compatible from application point of view, but requires backbone network deployment before any application can enter the next step. It does not give applications new functions.

Major issues: #4526 #4527 #4568 #4517 #4518

## Application Adoption

In this step, all application must stop using deprecated library APIs. Specifically, they cannot use:

* MinSuffixComponents

* MaxSuffixComponents, except via CanBePrefix functions

* PublisherPublicKeyLocator

* Exclude

* ChildSelector

Library API shall provide a per-application setting to set the initial value of CanBePrefix. The default setting is CanBePrefix=1. The application must explicitly declare whether they want CanBePrefix to be initialized to 0 or 1. If an application did not invoke this function, the Interest class constructor shall log a warning message indicating that the default will change in the future.

This step prepares NDN applications so that they do not rely on v0.2-only features, which will disappear in the next step.

Major issues: #4522 #4555 #4556 #4571 #4581 #4589 #4660 #4664 #4665 #4684 #4807 [~~ndn-traffic-generator#9~~](https://github.com/named-data/ndn-traffic-generator/issues/9) [ndnfs-port#10](https://github.com/remap/ndnfs-port/issues/10)

## 2-to-3 Interpretation

In this step, NDN entities shall transmit v0.3 packets, and process all packets with v0.3 semantics. A received v0.2 packet is interpreted as the closest v0.3 packet. Specifically:

* MinSuffixComponents, PublisherPublicKeyLocator, Exclude, and ChildSelector are ignored.

* MaxSuffixComponents>0 becomes CanBePrefix=0. Otherwise, CanBePrefix=1.

* HopLimit and Parameters are accepted and processed.

Packets shall be encoded as v0.3 format and processed with v0.3 semantics.

Received v0.2 packets may be forwarded as-is and re-encoding is not required (but permitted).

Library API shall enable access to typed name components, HopLimit, and Parameters.

This step transforms the network to use v0.3 format and semantics. It will break applications that have not completed the "application adoption" step.

Major issues: #4567 #4658 #4805 #4806

## CanBePrefix Switchover

Library's default setting for the initial value of CanBePrefix becomes CanBePrefix=0. This change does not affect applications that have explicitly declared their preference in "application adoption" step. This setting is expected to remain in the library for long term.

This step discourages the use of CanBePrefix=1 to improve network performance. It will potentially break applications that did not explicitly declare their preference.

Major issues: #4582

## Pure v0.3

In this step, NDN entities stop accepting v0.2 packets. It will break entities that have not completed the "2-to-3 interpretation" step.

Major issues: