FIP-0027: Use a Union type for the Label field

FIPS/fip-0027.md

@@ -1,7 +1,7 @@
 ---
 fip: "0027"
-title: Change type of DealProposal Label field from String to byte array
-author: Laudiacay (@laudiacay)
+title: Change type of DealProposal Label field from a (Golang) String to a Union
+author: Laudiacay (@laudiacay), Steven Allen (@Stebalien), Aayush Rajasekaran (@arajasek)
 discussions-to: https://github.com/filecoin-project/FIPs/issues/187
 Status: Draft
 type: Technical
@@ -16,38 +16,73 @@ spec-sections:
 
 ## Simple Summary
 <!--"If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the FIP.-->
-DealProposal's Label field is currently a String, but is not enforced to be UTF-8. This is not only outside the CBOR string specification, but can also be a source of bugs and difficulties in client implementations due to variations in String libraries. Rather than enforce it as UTF-8 everywhere, this FIP changes the type to be raw bytes for ease of implementation, bug avoidance, and CBOR compliance.
+Makers of deals on Filecoin can specify a "label" for their deals. This label is stored on the Filecoin blockchain, so it is important that there be no risk that a "bad" label can cause issues in nodes on the Filecoin network. Today, Filecoin does not enforce that this label meet UTF-8 encoding, even though valid CBOR-encoded strings must be UTF-8. 
+It is also increasingly the case that systems assume all strings are UTF-8 (see [here](https://en.wikipedia.org/wiki/Popularity_of_text_encodings#Popularity_internally_in_software) for more). This FIP proposes making a change to remove this abnormality.
 
 ## Abstract
 <!--A short (~200 word) description of the technical issue being addressed.-->
-String libraries differ in implementation of UTF-8. For maximum standardization and ease of bug-free client implementations, the DealProposal label should be raw bytes. Further, non-UTF-8 CBOR strings are technically outside of the CBOR specification, so the current implementation is outside of CBOR spec.
+The market state's `DealProposal`'s `Label` field is currently a `String` that is not enforced to be UTF-8. This is outside the CBOR string specification, and can also be a source of bugs and difficulties in client implementations due to variations in String libraries. Rather than enforce it as UTF-8 everywhere, this FIP changes the type to be a Union type that can be either Strings or raw bytes. This meets the goal of CBOR compliance and safety, while still allowing for users to have arbitrary bytes as the `Label`.
 
 ## Change Motivation
 <!--The motivation is critical for FIPs that want to change the Filecoin protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the FIP solves. FIP submissions without sufficient motivation may be rejected outright.-->
 
-Discussion is here: https://github.com/filecoin-project/specs-actors/issues/1248
+Discussion is [here](https://github.com/filecoin-project/specs-actors/issues/1248) and [here](https://github.com/filecoin-project/builtin-actors/issues/69)
 
 Summary: @ec2 noted that the non-UTF8 strings in this field are causing problems for the client implementations like ChainSafe. @ribasushi noticed that the Label field takes user input more or less directly, so enforcing UTF-7 might be difficult and pointless. Finally, @mikeal posted notes from an IPLD call saying that the source of the problem is that some programming languages enforce UTF-8 on Strings, while others don't, so the most widely compatible type for any on-chain data like this would be to just use a byte array.
 
 ## Specification
 <!--The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Filecoin implementations. -->
 
-The Label field of DealProposal should be CBOR bytes with arbitrary data allowed inside.
+The proposal is to change the `Label` to be a Union type, with the following IPLD schema:
+
+```
+type Label union {
+  | String string
+  | Bytes bytes
+} representation kinded
+```
+
+String-type labels will be enforced to be UTF-8. An analogous type can be seen [here](https://github.com/filecoin-project/go-hamt-ipld/blob/8cf7cf9309c8f38dbc15d3673b2354c041817884/hamt.go#L92-L145), with its encoding found [here](https://github.com/filecoin-project/go-hamt-ipld/blob/8cf7cf9309c8f38dbc15d3673b2354c041817884/pointer_cbor.go).
 
 ## Design Rationale
 <!--The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.-->
 
-Design decisions are in above sections.
+For simplicity and largest possible user-functionality, the ideal design would have just been to use a byte array. However, naively changing the `Label` field in the `DealProposal` from a string to bytes changes the serialization of the `DealProposal`. The current dealmaking flow on Filecoin is as follows (some aspects of this flow aren't protocol-specific, but might as well be, because they reflect the reality of dealmaking on Filecoin today):
+
+1) Client creates a `DealProposal`, signs it, wraps the proposal and signature into a `ClientDealProposal`, and sends that to the Storage Provider (SP)
+2) SP deserializes the `ClientDealProposal`, validates the signature, adds it to a batch, and eventually `PublishStorageDeals` (sending the serialized `ClientDealProposal` to the chain)
+3) Validators of the Filecoin blockchain:
+  - deserialize the `ClientDealProposal` into a `DealProposal` and a signature
+  - serialize the `DealProposal` 
+  - validate that the signature is valid for the serialized `DealProposal`
+
+The issue is that all the de/serializaton steps fail if they were done on opposite sides of the switch from string to bytes. It is not clear when clients should start using bytes instead of strings, or when SPs should start expecting clients to be using bytes instead of strings. Further, all `PublishStorageDeals` messages in node message pools (waiting to be included in a block) at the time of the network upgrade will fail when they land on chain.
+
+The Union type solves most of the problems described above. A large refactor may still be needed for client implementations if they don't abstract over possible `DealProposal`, but we avoid a messy period over the upgrade where large swathes of `PublishStorageDeals` messages fail on-chain and large numbers of clients are seeing SPs reject their deal proposals as invalid.
 
 ## Backwards Compatibility
 <!--All FIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The FIP must explain how the author proposes to deal with these incompatibilities. FIP submissions without a sufficient backwards compatibility treatise may be rejected outright.-->
 
-This changes specs-actors. All deal proposals on chain will need to change the encoding of the label field.
+A migration is needed in the network upgrade that introduces this FIP. The migration runs over all `DealProposal`s on chain, applying the following rule:
+
+- If `Label` is UTF-8, use the `string` type of the Union
+- Else, use the bytes type.
+
+Note that this means that most deals will actually not have their encodings change at all, since most deals on Filecoin today _do_ have UTF-8 encoded `Label`s.
 
 ## Test Cases
 <!--Test cases for an implementation are mandatory for FIPs that are affecting consensus changes. Other FIPs can choose to include links to test cases if applicable.-->
 
-Test that v0-v6 proposals' String labels become CBOR bytes with the same raw byte payload after migration, and that new proposals have labels encoded as CBOR bytes.
+Test that:
+
+- New deals can be created with UTF-8 string labels, and can be encoded and decoded
+- New deals can be created with byte string labels, and can be encoded and decoded
+- New deals CANNOT be created with non-UTF-8 string labels
+
+Additionally, migration testing should ensure that:
+
+- Existing deals with UTF-8 `Label`s are migrated to Unions with strings, and the CBOR encoding of such deals DO NOT change
+- Existing deals with non-UTF-8 `Label`s are migrated to Unions with bytes, and the CBOR encoding of such deals do change
 
 ## Security Considerations
 <!--All FIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. E.g. include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. FIP submissions missing the "Security Considerations" section will be rejected. A FIP cannot proceed to status "Final" without a Security Considerations discussion deemed sufficient by the reviewers.-->
@@ -67,7 +102,11 @@ This should have a positive effect on the ecosystem as a whole, because implemen
 ## Implementation
 <!--The implementations must be completed before any core FIP is given status "Final", but it need not be completed before the FIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.-->
 
-[Here](https://github.com/filecoin-project/specs-actors/pull/1496)
+A prototype of this implementation on top of the v7 actors release can be seen [here](https://github.com/filecoin-project/specs-actors/commit/c755c0402f62e049c96cc855b46cf123f0958c5c). The actual implementation will have to be on a new version (v8) of actors, but this is useful to test backwards compatibility.
+
+## Future considerations
+
+In a subsequent network upgrade, we can consider a FIP that replaces this type with simple byte strings (the ideal design described in the Design Rational section). With sufficient communication, we can announce that support for String labels is being deprecated ahead of time, allowing all users to start using byte strings instead.
 
 ## Copyright
 Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).