Merge pull request #30 from starknet-io/shahak/protocol_overview

Add detailed description to all protocols.

README.md

@@ -4,4 +4,4 @@ This repo contains and tracks the specification of P2P protocol for StarkNet nod
 
 The main entry point is the [here](./p2p/starknet-p2p.md).
 
-For a guide on how to implement the protocols, see [here](./p2p/proto/protocols.md)
+For a guide on the various protocols of Starknet and how to implement them, see [here](./p2p/proto/protocols.md)

p2p/proto/class.proto

@@ -4,15 +4,16 @@ import "p2p/proto/common.proto";
 
 message EntryPoint {
     Felt252 selector = 1;
-    Felt252 offset = 2;
+    uint64 offset = 2;
 }
 
 message Cairo0Class {
-    bytes abi = 1;
+    string abi = 1;
     repeated EntryPoint externals = 2;
     repeated EntryPoint l1_handlers = 3;
     repeated EntryPoint constructors = 4;
-    bytes program = 5;
+    // Compressed in base64 representation.
+    string program = 5;
 }
 
 message SierraEntryPoint {
@@ -27,24 +28,18 @@ message Cairo1EntryPoints {
 }
 
 message Cairo1Class {
-    bytes abi = 1;
+    string abi = 1;
     Cairo1EntryPoints entry_points = 2;
     repeated Felt252 program = 3;
     string contract_class_version = 4;
-    bytes compiled = 5;
 }
 
-// is it better to separate the definition from the hashes? (will need to repeate the hashes
-// for the definitions stream)
-// or, make the definitions optional? maybe it is enough to know only that a class exists, not its definition
-// which may be fetched lazily later.
 message Class {
     oneof class {
         Cairo0Class cairo0 = 1;
         Cairo1Class cairo1 = 2;
     }
     uint32 domain = 3;
-    Hash class_hash = 4;
 }
 
 message ClassesRequest {

p2p/proto/common.proto

@@ -20,25 +20,40 @@ message PeerID {
     bytes id = 1;
 }
 
+message Uint128 {
+    uint64 low = 1;
+    uint64 high = 2;
+}
+
 message ConsensusSignature {
     Felt252 r = 1;
     Felt252 s = 2;
 }
 
-message Merkle {
-    uint32 n_leaves = 1;  // needed to know the height, so as to how many nodes to expect in a proof.
+message Patricia {
+    uint64 n_leaves = 1;  // needed to know the height, so as to how many nodes to expect in a proof.
                           // and also when receiving all leaves, how many to expect
-    Hash   root     = 2;
+    Hash root = 2;
 }
 
-message Patricia {
-    uint32 height = 1;
-    Hash   root   = 2;
+message StateDiffCommitment {
+    uint64 state_diff_length = 1;
+    Hash root = 2;
 }
 
 message BlockID {
     uint64 number = 1;
-    Hash   header = 2;
+    Hash header = 2;
+}
+
+enum L1DataAvailabilityMode {
+    Calldata = 0;
+    Blob = 1;
+}
+
+enum VolitionDomain {
+    L1 = 0;
+    L2 = 1;
 }
 
 message Iteration {
@@ -48,11 +63,11 @@ message Iteration {
     }
     oneof start {
         uint64 block_number = 1;
-        Hash   header       = 2;
+        Hash header = 2;
     }
     Direction direction = 3;
-    uint64    limit     = 4;
-    uint64    step      = 5;  // to allow interleaving from several nodes
+    uint64 limit = 4;
+    uint64 step = 5;  // to allow interleaving from several nodes
     // bool interleave = 6; // return results in any order of blocks, per block the messages should still be in the order specified
 }
 

p2p/proto/consensus.proto

@@ -9,34 +9,34 @@ import "google/protobuf/timestamp.proto";
 // WIP - will change
 
 message Proposal {
-    uint64                    block_number      = 2;
-    uint32                    round             = 3;
-    uint32                    pol               = 4;  // proof of lock
-    Hash                      block_header_hash = 5;
-    google.protobuf.Timestamp timestamp         = 6;
-    ConsensusSignature        signature         = 7;
+    uint64 block_number = 1;
+    uint32 round = 2;
+    uint32 pol = 3;  // proof of lock
+    Hash block_header_hash = 4;
+    google protobuf Timestamp timestamp = 5;
+    ConsensusSignature signature = 6;
 }
 
 // A block proposal is a series of (Transactions+, StateDiff)* BlockHeader
 
 message Vote {
     enum  Type {
-        UNKNOWN   = 0;
-        Proposal  = 1;
-        Prevote   = 2;
+        UNKNOWN = 0;
+        Proposal = 1;
+        Prevote = 2;
         Precommit = 3;
     };
 
-    Proposal           proposal          = 1;
-    Address            validator_address = 2;
-    int32              validator_index   = 3;  // ???
-    ConsensusSignature signature         = 4;
+    Proposal proposal = 1;
+    Address validator_address = 2;
+    int32 validator_index = 3;  // ???
+    ConsensusSignature signature = 4;
 }
 
 message CreateBlock {
     oneof messages {
         Transactions transactions = 1;
-        StateDiff    state_diff   = 2;
-        Proposal     proposal     = 3;
+        StateDiff state_diff = 2;
+        Proposal proposal = 3;
     }
 }

p2p/proto/event.proto

@@ -3,9 +3,9 @@ import "p2p/proto/common.proto";
 
 message Event {
     Hash transaction_hash = 1;
-    Felt252  from_address = 2;
-    repeated Felt252 keys = 3;
-    repeated Felt252 data = 4;
+    Felt252 from_address = 3;
+    repeated Felt252 keys = 4;
+    repeated Felt252 data = 5;
 }
 
 message EventsRequest {
@@ -16,6 +16,6 @@ message EventsRequest {
 message EventsResponse {
     oneof event_message {
         Event event = 1;
-        Fin   fin   = 2; // Fin is sent after the peer sent all the data or when it encountered a block that it doesn't have its events.
+        Fin fin = 2; // Fin is sent after the peer sent all the data or when it encountered a block that it doesn't have its events.
     }
 }

p2p/proto/header.proto

@@ -1,38 +1,37 @@
 syntax = "proto3";
 import "p2p/proto/common.proto";
-import "p2p/proto/state.proto";
 
 // Note: commitments may change to be for the previous blocks like comet/tendermint
 // hash of block header sent to L1
 message SignedBlockHeader {
-    Hash                        block_hash              = 1; //  For the structure of the block hash, see https://docs.starknet.io/documentation/architecture_and_concepts/Network_Architecture/header/#block_hash
-    Hash                        parent_hash             = 2;
-    uint64                      number                  = 3;
-    uint64                      time                    = 4;   // Encoded in Unix time.
-    Address                     sequencer_address       = 5;
-    Hash                        state_diff_commitment   = 6;   //  The state diff commitment returned  by the Starknet Feeder Gateway.
-                                                             //  For more info, see https://community.starknet.io/t/introducing-p2p-authentication-and-mismatch-resolution-in-v0-12-2/97993
-    Patricia                    state                   = 7;   // hash of contract and class patricia tries. Same as in L1. Later more trees will be included
-    // The following merkles can be built on the fly while sequencing/validating txs.
-    Merkle                      transactions            = 8;   // By order of execution. TBD: required? the client can execute (powerful machine) and match state diff
-    Merkle                      events                  = 9;   // By order of issuance. TBD: in receipts?
-    Merkle                      receipts                = 10;  // By order of issuance.
-    string                      protocol_version        = 11; // Starknet version
-    Felt252                     gas_price               = 12;
-    uint64                      num_storage_diffs       = 13;
-    uint64                      num_nonce_updates       = 14;
-    uint64                      num_declared_classes    = 15;  // Includes both Cairo 0 and Cairo 1.
-    uint64                      num_deployed_contracts  = 16;  // This includes the replaced classes too.
+    Hash block_hash = 1; //  For the structure of the block hash, see https://docs.starknet.io/documentation/architecture_and_concepts/Network_Architecture/header/#block_hash
+    Hash parent_hash = 2;
+    uint64 number = 3; // This can be deduced from context. We can consider removing this field.
+    uint64 time = 4; // Encoded in Unix time.
+    Address sequencer_address = 5;
+    Hash state_root = 6;   // Patricia root of contract and class patricia tries. Each of those tries are of height 251. Same as in L1. Later more trees will be included
+    StateDiffCommitment state_diff_commitment = 7; // The state diff commitment returned  by the Starknet Feeder Gateway
+    // For more info, see https://community.starknet.io/t/introducing-p2p-authentication-and-mismatch-resolution-in-v0-12-2/97993
+    // The leaves contain a hash of the transaction hash and transaction signature.
+    Patricia transactions = 8;   // By order of execution. TBD: required? the client can execute (powerful machine) and match state diff
+    Patricia events = 9;   // By order of issuance. TBD: in receipts?
+    Hash receipts = 10;  // By order of issuance. This is a patricia root. No need for length because it's the same length as transactions.
+    string protocol_version = 11; // Starknet version
+    Uint128 gas_price_fri = 12;
+    Uint128 gas_price_wei = 13;
+    Uint128 data_gas_price_fri = 14;
+    Uint128 data_gas_price_wei = 15;
+    L1DataAvailabilityMode l1_data_availability_mode = 16;
     // for now, we assume a small consensus, so this fits in 1M. Else, these will be repeated and extracted from this message.
-    repeated ConsensusSignature signatures              = 17;
-                                       // can be more explicit here about the signature structure as this is not part of account abstraction
+    repeated ConsensusSignature signatures = 17;
+    // can be more explicit here about the signature structure as this is not part of account abstraction
 }
 
 // sent to all peers (except the ones this was received from, if any).
 // for a fraction of peers, also send the GetBlockHeaders response (as if they asked for it for this block)
 message NewBlock {
     oneof maybe_full {
-        BlockID              id     = 1;
+        BlockID id = 1;
         BlockHeadersResponse header = 2;
     }
 }
@@ -46,6 +45,6 @@ message BlockHeadersRequest {
 message BlockHeadersResponse {
     oneof header_message {
         SignedBlockHeader header = 1;
-        Fin               fin    = 2; // Fin is sent after the peer sent all the data or when it encountered a block that it doesn't have its header.
+        Fin fin = 2; // Fin is sent after the peer sent all the data or when it encountered a block that it doesn't have its header.
     }
 }

p2p/proto/mempool.proto

@@ -9,7 +9,7 @@ message PooledTransactionsRequest
 {
     message Known {
         oneof known {
-            Hashes txs    = 1;  // for mempool of 2000 txs, this will be 64K. Can use Hash32 instead (8K)...
+            Hashes txs = 1;  // for mempool of 2000 txs, this will be 64K. Can use Hash32 instead (8K)...
             uint64 marker = 2;  // since last returned marker.
         }
     }
@@ -20,11 +20,11 @@ message PooledTransactionsRequest
 // can propagate it without being pulled
 // nodes should track state diffs to know when txs have been included (the contract nonce increases)
 message PolledTransactionsResponse {
-    optional uint64   marker = 1;  // optional, if the peer supports that.
-    bool     baseline        = 2;  // means treat all data as baseline, not diff (may be if 'known' was sent but the mempool was reset/reorged
+    optional uint64 marker = 1;  // optional, if the peer supports that.
+    bool baseline = 2;  // means treat all data as baseline, not diff (may be if 'known' was sent but the mempool was reset/reorged
 
     oneof responses {
-        Transactions pending  = 3;  // if 'known' is given, they will be only txs added after the known
-        Fin          fin      = 4;
+        Transactions pending = 3;  // if 'known' is given, they will be only txs added after the known
+        Fin fin = 4;
     }
 }