From 11dc422ccae64aea4400680d7d269e34beb51d71 Mon Sep 17 00:00:00 2001 From: whyrusleeping Date: Tue, 5 Feb 2019 17:39:23 -0800 Subject: [PATCH 1/4] initial compact serialization proposal --- data-structures.md | 59 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 41 insertions(+), 18 deletions(-) diff --git a/data-structures.md b/data-structures.md index 650bf2eca..a57ea2ba8 100644 --- a/data-structures.md +++ b/data-structures.md @@ -2,7 +2,6 @@ This document serves as an entry point for understanding all of the data structures in filecoin. -TODO: this should also include, or reference, how each data structure is serialized precisely. ## Address @@ -71,10 +70,6 @@ type Block struct { } ``` -### Serialization - -Blocks are currently serialized simply by CBOR marshaling them, using lower-camel-cased field names. - ## Message ```go @@ -85,9 +80,9 @@ type Message struct { // When receiving a message from a user account the nonce in // the message must match the expected nonce in the from actor. // This prevents replay attacks. - Nonce Integer + Nonce Uint64 - Value Integer + Value BigInteger GasPrice Integer GasLimit Integer @@ -100,6 +95,7 @@ type Message struct { ### Parameter Encoding Parameters to methods get encoded as described in the [basic types](#basic-type-encodings) section below, and then put into a CBOR encoded array. +(TODO: thinking about this, it might make more sense to just have `Params` be an array of things) ### Signing @@ -114,9 +110,17 @@ type SignedMessage struct { The signature is a serialized signature over the serialized base message. For more details on how the signature itself is done, see the [signatures spec](signatures.md). -### Serialization +## MessageReceipt -Messages and SignedMessages are currently serialized simply by CBOR marshaling them, using lower-camel-cased field names. +```go +type MessageReceipt struct { + ExitCode uint8 + + Return [][]byte + + GasUsed BigInteger +} +``` ## Message Receipt @@ -147,20 +151,13 @@ type Actor struct { Head Cid // Nonce is a counter of the number of messages this actor has sent - Nonce Integer + Nonce Uint64 // Balance is this actors current balance of filecoin - Balance AttoFIL + Balance BigInteger } ``` - - - -### Serialization - -Actors are currently serialized simply by CBOR marshaling them, using lower-camel-cased field names. - ## State Tree The state trie keeps track of all state in Filecoin. It is a map of addresses to `actors` in the system. It is implemented using a HAMT. @@ -169,6 +166,7 @@ The state trie keeps track of all state in Filecoin. It is a map of addresses to TODO: link to spec for our CHAMP HAMT + # Basic Type Encodings Types that appear in messages or in state must be encoded as described here. @@ -295,3 +293,28 @@ if ((shift [msg.To, msg.From, msg.Nonce, msg.Value, msg.Method, msg.Params] +``` + +Each individual type should be encoded as specified: + +| type | encoding | +| --- | ---- | +| Uint64 | CBOR major type 0 | +| BigInteger | [CBOR bignum](https://tools.ietf.org/html/rfc7049#section-2.4.2) | +| Address | CBOR major type 2 | From a768007f33a9885be4fdb2ff10dcaa2c024a1f2d Mon Sep 17 00:00:00 2001 From: whyrusleeping Date: Wed, 6 Feb 2019 09:23:44 -0800 Subject: [PATCH 2/4] addressing review --- data-structures.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/data-structures.md b/data-structures.md index a57ea2ba8..8d292dcad 100644 --- a/data-structures.md +++ b/data-structures.md @@ -296,7 +296,7 @@ if ((shift Date: Tue, 26 Feb 2019 14:34:54 -0800 Subject: [PATCH 3/4] address review feedback --- data-structures.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/data-structures.md b/data-structures.md index 8d292dcad..243107b93 100644 --- a/data-structures.md +++ b/data-structures.md @@ -298,12 +298,11 @@ if ((shift Date: Thu, 21 Mar 2019 12:03:49 -0700 Subject: [PATCH 4/4] add note on ipld cid multicodec --- data-structures.md | 8 +++++++- definitions.md | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/data-structures.md b/data-structures.md index 243107b93..0ce9f86f9 100644 --- a/data-structures.md +++ b/data-structures.md @@ -28,6 +28,7 @@ For most objects referenced by Filecoin, a Content Identifier (CID for short) is CIDs are serialized by applying binary multibase encoding, then encoding that as a CBOR byte array with a tag of 42. + ## Block A block represents an individual point in time that the network may achieve consensus on. It contains (via merkle links) the full state of the system, references to the previous state, and some notion of a 'weight' for deciding which block is the 'best'. @@ -315,14 +316,19 @@ Each individual type should be encoded as specified: | type | encoding | | --- | ---- | | Uint64 | CBOR major type 0 | -| BigInteger | [CBOR bignum](https://tools.ietf.org/html/rfc7049#section-2.4.2) | +| BigInteger | [CBOR bignum](https://tools.ietf.org/html/rfc7049#section-2.4.2) | | Address | CBOR major type 2 | | Uint8 | CBOR Major type 0 | | []byte | CBOR Major type 2 | | string | CBOR Major type 3 | +| bool | [CBOR Major type 7, value 20/21](https://tools.ietf.org/html/rfc7049#section-2.3) | ## Encoding Considerations Objects should be encoded using [canonical CBOR](https://tools.ietf.org/html/rfc7049#section-3.9), and decoders should operate in [strict mode](https://tools.ietf.org/html/rfc7049#section-3.10). The maximum size of an FCS Object should be 1MB (2^20 bytes). Objects larger than this are invalid. Additionally, CBOR Major type 5 is not used. If an FCS object contains it, that object is invalid. + +## IPLD Considerations + +Cids for FCS objects should use the FCS multicodec (`0x1f`). diff --git a/definitions.md b/definitions.md index 86686d868..aa494baca 100644 --- a/definitions.md +++ b/definitions.md @@ -97,7 +97,7 @@ See [Filecoin Proofs](proofs.md) #### Leader -A leader, in the context of Filecoin consensus, is a node that is chosen to propose the next block in the blockchain. +A leader, in the context of Filecoin consensus, is a node that is chosen to propose the next block in the blockchain. #### Leader election