initial compact serialization proposal

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
 
@@ -29,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'.
@@ -71,10 +71,6 @@ type Block struct {
 }
 ```
 
-### Serialization
-
-Blocks are currently serialized simply by CBOR marshaling them, using lower-camel-cased field names.
-
 ## Message
 
 ```go
@@ -85,9 +81,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 +96,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 +111,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
+
+```go
+type MessageReceipt struct {
+    ExitCode uint8
+
+    Return [][]byte
 
-Messages and SignedMessages are currently serialized simply by CBOR marshaling them, using lower-camel-cased field names.
+    GasUsed BigInteger
+}
+```
 
 ## Message Receipt
 
@@ -147,20 +152,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 +167,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 +294,41 @@ if ((shift <size) && (sign bit of byte is set))
   /* sign extend */
   result |= - (1 << shift);
 ```
+
+# Filecoin Compact Serialization
+
+Datastructures in Filecoin are encoded as compactly as is reasonable. At a high level, each object is converted into an ordered array of its fields (ordered by their appearance in the struct declaration), then CBOR marshaled, and prepended with an object type tag.
+
+| FCS Type | tag  |
+|---|---|
+| block v1 | 43  |
+| message v1 | 44 |
+| signedMessage v1 | 45 |
+
+For example, a message would be encoded as:
+
+```cbor
+tag<44>[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 |
+| 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`).

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