Skip to content

Commit

Permalink
Add more detail to the Union label proposal
Browse files Browse the repository at this point in the history
  • Loading branch information
arajasek committed Mar 12, 2022
1 parent 77ed337 commit e854378
Showing 1 changed file with 8 additions and 4 deletions.
12 changes: 8 additions & 4 deletions FIPS/fip-0027.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
fip: "0027"
title: Change type of DealProposal Label field from String to a Union
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
Expand All @@ -20,7 +20,7 @@ Makers of deals on Filecoin can specify a "label" for their deals. This label is

## Abstract
<!--A short (~200 word) description of the technical issue being addressed.-->
The market state's `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 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`.
The market state's `DealProposal`'s `Label` field is currently a Golang `String`, which 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.-->
Expand All @@ -47,7 +47,7 @@ We apply the following rules:
- De/serialize this object as though it were just one field -- "If label_string is set, serialize it as a string, if not, serialize it as bytes" (and the reverse for decoding). This is NOT the default CBOR encoding of such a struct, custom encoding must be written.
- Assert that if `label_string` is set, it is valid UTF-8. This check would automatically happen in a language like (safe) Rust, and can be enforced at the CBOR level for other languages.

An analagous 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).
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.-->
Expand Down Expand Up @@ -107,7 +107,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/).

0 comments on commit e854378

Please sign in to comment.