op-erigon-interfaces

diff: ignored:
+266
-126
+14
-13

This is an overview of the changes in op-erigon-interfaces, a fork of erigon-interface.

op-erigon extends existing gRPC for new RPC definitions and extraneous data that Optimism utilizes.

diff --git erigontech/interfaces/downloader/downloader.proto testinprod-io/erigon-interfaces/downloader/downloader.proto index 4f3bd722e0524b2f430a3b3ed0ed5b8260d2d794..26d3fbb0850e0aeb7b9170c52727eb90ec8e708f 100644 --- erigontech/interfaces/downloader/downloader.proto +++ testinprod-io/erigon-interfaces/downloader/downloader.proto @@ -8,7 +8,17 @@ package downloader;   service Downloader { - rpc Download (DownloadRequest) returns (google.protobuf.Empty) {} + // Erigon "download once" - means restart/upgrade/downgrade will not download files (and will be fast) + // After "download once" - Erigon will produce and seed new files + // Downloader will able: seed new files (already existing on FS), download uncomplete parts of existing files (if Verify found some bad parts) + rpc ProhibitNewDownloads (ProhibitNewDownloadsRequest) returns (google.protobuf.Empty) {} + + // Adding new file to downloader: non-existing files it will download, existing - seed + rpc Add (AddRequest) returns (google.protobuf.Empty) {} + rpc Delete (DeleteRequest) returns (google.protobuf.Empty) {} + + // Trigger verification of files + // If some part of file is bad - such part will be re-downloaded (without returning error) rpc Verify (VerifyRequest) returns (google.protobuf.Empty) {} rpc Stats (StatsRequest) returns (StatsReply) {} } @@ -16,12 +26,17 @@ // DownloadItem: // - if Erigon created new snapshot and want seed it // - if Erigon wnat download files - it fills only "torrent_hash" field -message DownloadItem { +message AddItem { string path = 1; types.H160 torrent_hash = 2; // will be resolved as magnet link } -message DownloadRequest { - repeated DownloadItem items = 1; // single hash will be resolved as magnet link +message AddRequest { + repeated AddItem items = 1; // single hash will be resolved as magnet link +} + +// DeleteRequest: stop seeding, delete file, delete .torrent +message DeleteRequest { + repeated string paths = 1; }   message VerifyRequest { @@ -29,6 +44,10 @@ }   message StatsRequest { +} + +message ProhibitNewDownloadsRequest { + string type = 1; }   message StatsReply {
diff --git erigontech/interfaces/execution/execution.proto testinprod-io/erigon-interfaces/execution/execution.proto index 8a12955106030b39de0f1a3f3f2a51707ec6147b..8356e09337048c0c0ed4fc236013f53be9e8d86f 100644 --- erigontech/interfaces/execution/execution.proto +++ testinprod-io/erigon-interfaces/execution/execution.proto @@ -2,27 +2,31 @@ syntax = "proto3";   package execution;   +import "google/protobuf/empty.proto"; import "types/types.proto";   option go_package = "./execution;execution";   -enum ValidationStatus { - Success = 0; // State transition simulation is successful. - InvalidChain = 1; // State transition simulation is Unsuccessful. - TooFarAway = 2; // Chain hash is too far away from current chain head and unfeasible to validate. - MissingSegment = 3; // Chain segments are missing. +enum ExecutionStatus { + Success = 0; + BadBlock = 1; + TooFarAway = 2; + MissingSegment = 3; + InvalidForkchoice = 4; + Busy = 5; }   message ForkChoiceReceipt { - bool success = 1; // Forkchoice is either successful or unsuccessful. + ExecutionStatus status = 1; types.H256 latest_valid_hash = 2; // Return latest valid hash in case of halt of execution. + string validation_error = 3; }   // Result we receive after validation message ValidationReceipt { - ValidationStatus validation_status = 1; + ExecutionStatus validation_status = 1; types.H256 latest_valid_hash = 2; - optional types.H256 missing_hash = 3; // The missing hash, in case we receive MissingSegment so that we can reverse download it. + string validation_error = 3; };   message IsCanonicalResponse { @@ -36,7 +40,7 @@ types.H160 coinbase = 2; types.H256 state_root = 3; types.H256 receipt_root = 4; types.H2048 logs_bloom = 5; - types.H256 mix_digest = 6; + types.H256 prev_randao = 6; uint64 block_number = 7; uint64 gas_limit = 8; uint64 gas_used = 9; @@ -48,8 +52,13 @@ types.H256 block_hash = 14; // We keep this so that we can validate it types.H256 ommer_hash = 15; types.H256 transaction_hash = 16; optional types.H256 base_fee_per_gas = 17; - optional types.H256 withdrawal_hash = 18; - optional types.H256 excess_data_gas = 19; + optional types.H256 withdrawal_hash = 18; // added in Shapella (EIP-4895) + optional uint64 blob_gas_used = 19; // added in Dencun (EIP-4844) + optional uint64 excess_blob_gas = 20; // added in Dencun (EIP-4844) + optional types.H256 parent_beacon_block_root = 21; // added in Dencun (EIP-4788) + // AuRa + optional uint64 aura_step = 22; + optional bytes aura_seal = 23; }   // Body is a block body for execution @@ -60,12 +69,21 @@ // Raw transactions in byte format. repeated bytes transactions = 3; repeated Header uncles = 4; repeated types.Withdrawal withdrawals = 5; +} + +message Block { + Header header = 1; + BlockBody body = 2; }   message GetHeaderResponse { optional Header header = 1; }   +message GetTDResponse { + optional types.H256 td = 1; +} + message GetBodyResponse { optional BlockBody body = 1; } @@ -80,27 +98,113 @@ optional uint64 block_number = 1; optional types.H256 block_hash = 2; }   -message InsertHeadersRequest { - repeated Header headers = 1; +message InsertBlocksRequest { + repeated Block blocks = 1; }   -message InsertBodiesRequest { + +message ForkChoice { + types.H256 head_block_hash = 1; + uint64 timeout = 2; // Timeout in milliseconds for fcu before it becomes async. + optional types.H256 finalized_block_hash = 3; + optional types.H256 safe_block_hash = 4; +} + +message InsertionResult { + ExecutionStatus result = 1; +} + +message ValidationRequest { + types.H256 hash = 1; + uint64 number = 2; +} + +message AssembleBlockRequest { + types.H256 parent_hash = 1; + uint64 timestamp = 2; + types.H256 prev_randao = 3; + types.H160 suggested_fee_recipient = 4; + repeated types.Withdrawal withdrawals = 5; // added in Shapella (EIP-4895) + optional types.H256 parent_beacon_block_root = 6; // added in Dencun (EIP-4788) + + // optimism + repeated bytes transactions = 7; + bool no_tx_pool = 8; + optional uint64 gas_limit = 9; +} + +message AssembleBlockResponse { + uint64 id = 1; + bool busy = 2; +} + +message GetAssembledBlockRequest { + uint64 id = 1; +} + +message AssembledBlockData { + types.ExecutionPayload execution_payload = 1; + types.H256 block_value = 2; + types.BlobsBundleV1 blobs_bundle = 3; + optional types.H256 parent_beacon_block_root = 4; +} + +message GetAssembledBlockResponse { + optional AssembledBlockData data = 1; + bool busy = 2; +} + +message GetBodiesBatchResponse { repeated BlockBody bodies = 1; }   -message EmptyMessage {} +message GetBodiesByHashesRequest { + repeated types.H256 hashes = 1; +} + +message GetBodiesByRangeRequest { + uint64 start = 1; + uint64 count = 2; +} + +message ReadyResponse { + bool ready = 1; +} + +message FrozenBlocksResponse { + uint64 frozen_blocks = 1; +} + +message HasBlockResponse { + bool has_block = 1; +}   service Execution { // Chain Putters. - rpc InsertHeaders(InsertHeadersRequest) returns(EmptyMessage); - rpc InsertBodies(InsertBodiesRequest) returns(EmptyMessage); + rpc InsertBlocks(InsertBlocksRequest) returns(InsertionResult); // Chain Validation and ForkChoice. - rpc ValidateChain(types.H256) returns(ValidationReceipt); - rpc UpdateForkChoice(types.H256) returns(ForkChoiceReceipt); - rpc AssembleBlock(EmptyMessage) returns(types.ExecutionPayload); // Builds on top of current head. + rpc ValidateChain(ValidationRequest) returns(ValidationReceipt); + rpc UpdateForkChoice(ForkChoice) returns(ForkChoiceReceipt); + // Block Assembly + // EAGAIN design here, AssembleBlock initiates the asynchronous request, and GetAssembleBlock just return it if ready. + rpc AssembleBlock(AssembleBlockRequest) returns(AssembleBlockResponse); + rpc GetAssembledBlock(GetAssembledBlockRequest) returns(GetAssembledBlockResponse); // Chain Getters. + rpc CurrentHeader(google.protobuf.Empty) returns(GetHeaderResponse); + rpc GetTD(GetSegmentRequest) returns(GetTDResponse); rpc GetHeader(GetSegmentRequest) returns(GetHeaderResponse); rpc GetBody(GetSegmentRequest) returns(GetBodyResponse); + rpc HasBlock(GetSegmentRequest) returns(HasBlockResponse); + // Ranges + rpc GetBodiesByRange(GetBodiesByRangeRequest) returns(GetBodiesBatchResponse); + rpc GetBodiesByHashes(GetBodiesByHashesRequest) returns(GetBodiesBatchResponse); + // Chain checkers rpc IsCanonicalHash(types.H256) returns(IsCanonicalResponse); rpc GetHeaderHashNumber(types.H256) returns(GetHeaderHashNumberResponse); + rpc GetForkChoice(google.protobuf.Empty) returns(ForkChoice); + // Misc + // We want to figure out whether we processed snapshots and cleanup sync cycles. + rpc Ready(google.protobuf.Empty) returns(ReadyResponse); + // Frozen blocks are how many blocks are in snapshots .seg files. + rpc FrozenBlocks(google.protobuf.Empty) returns(FrozenBlocksResponse); }
diff --git erigontech/interfaces/p2psentinel/sentinel.proto testinprod-io/erigon-interfaces/p2psentinel/sentinel.proto index 5d3c84de47b21b3e54069126a4b33be377bc2cdb..6d35dcfa5f6f4acbb393f1ad2ee033e2e9e19f13 100644 --- erigontech/interfaces/p2psentinel/sentinel.proto +++ testinprod-io/erigon-interfaces/p2psentinel/sentinel.proto @@ -8,28 +8,34 @@ import "types/types.proto";   message EmptyMessage {}   -enum GossipType { - // Lightclient gossip - LightClientFinalityUpdateGossipType = 0; - LightClientOptimisticUpdateGossipType = 1; - // Legacy gossip - BeaconBlockGossipType = 2; - - // Global gossip topics. - AggregateAndProofGossipType = 3; - VoluntaryExitGossipType = 4; - ProposerSlashingGossipType = 5; - AttesterSlashingGossipType = 6; +message SubscriptionData { + optional string filter = 1; }   message Peer { string pid = 1; + string state = 2; + string direction = 3; + string address = 4; + string enr = 5; + string agent_version = 6; +} + + +message PeersInfoRequest { + optional string direction = 1; + optional string state = 2; +} + +message PeersInfoResponse { + repeated Peer peers = 1; }   message GossipData { bytes data = 1; // SSZ encoded data - GossipType type = 2; + string name = 2; optional Peer peer = 3; + optional uint64 subnet_id = 4; }   message Status { @@ -41,7 +47,11 @@ uint64 head_slot = 5; }   message PeerCount { - uint64 amount = 1; + uint64 active = 1; // Amount of peers that are active. + uint64 connected = 2; + uint64 disconnected = 3; + uint64 connecting = 4; + uint64 disconnecting = 5; }   message RequestData { @@ -52,13 +62,39 @@ message ResponseData { bytes data = 1; // prefix-stripped SSZ encoded data bool error = 2; // did the peer encounter an error + Peer peer = 3; +} + +message Metadata { + uint64 seq = 1; + string attnets = 2; + string syncnets = 3; +} + +message IdentityResponse { + string pid = 1; + string enr = 2; + repeated string p2p_addresses = 3; + repeated string discovery_addresses = 4; + Metadata metadata = 5; +} + +message RequestSubscribeExpiry { + string topic = 1; + uint64 expiry_unix_secs = 2; }   service Sentinel { - rpc SubscribeGossip(EmptyMessage) returns (stream GossipData); + rpc SetSubscribeExpiry(RequestSubscribeExpiry) returns(EmptyMessage); + rpc SubscribeGossip(SubscriptionData) returns (stream GossipData); rpc SendRequest(RequestData) returns (ResponseData); rpc SetStatus(Status) returns(EmptyMessage); // Set status for peer filtering. rpc GetPeers(EmptyMessage) returns (PeerCount); rpc BanPeer(Peer) returns(EmptyMessage); + rpc UnbanPeer(Peer) returns(EmptyMessage); + rpc PenalizePeer(Peer) returns(EmptyMessage); + rpc RewardPeer(Peer) returns(EmptyMessage); rpc PublishGossip(GossipData) returns(EmptyMessage); + rpc Identity(EmptyMessage) returns(IdentityResponse); // Returns the identity of the peer. + rpc PeersInfo(PeersInfoRequest) returns(PeersInfoResponse); // Returns the identity of the peer. }
diff --git erigontech/interfaces/p2psentry/sentry.proto testinprod-io/erigon-interfaces/p2psentry/sentry.proto index 1cfa977c881ba6e1bd50995630bc63684c756824..b0c11cbd9e978f55db08862147e407327d85f1e2 100644 --- erigontech/interfaces/p2psentry/sentry.proto +++ testinprod-io/erigon-interfaces/p2psentry/sentry.proto @@ -93,6 +93,10 @@ types.H512 peer_id = 1; uint64 min_block = 2; }   +message AddPeerRequest { + string url = 1; +} + message InboundMessage { MessageId id = 1; bytes data = 2; @@ -163,6 +167,10 @@ types.H512 peer_id = 1; PeerEventId event_id = 2; }   +message AddPeerReply { + bool success = 1; +} + service Sentry { // SetStatus - force new ETH client state of sentry - network_id, max_block, etc... rpc SetStatus(StatusData) returns (SetStatusReply); @@ -189,6 +197,8 @@ rpc PeerCount(PeerCountRequest) returns (PeerCountReply); rpc PeerById(PeerByIdRequest) returns (PeerByIdReply); // Subscribe to notifications about connected or lost peers. rpc PeerEvents(PeerEventsRequest) returns (stream PeerEvent); + + rpc AddPeer(AddPeerRequest) returns (AddPeerReply);   // NodeInfo returns a collection of metadata known about the host. rpc NodeInfo(google.protobuf.Empty) returns(types.NodeInfoReply);
diff --git erigontech/interfaces/remote/ethbackend.proto testinprod-io/erigon-interfaces/remote/ethbackend.proto index dd944fc8e37b944c31779fb5e291addd4404e245..c0a643e2f7113ba580d8ebfc0cb48f98f401f431 100644 --- erigontech/interfaces/remote/ethbackend.proto +++ testinprod-io/erigon-interfaces/remote/ethbackend.proto @@ -14,29 +14,6 @@ rpc NetVersion(NetVersionRequest) returns (NetVersionReply);   rpc NetPeerCount(NetPeerCountRequest) returns (NetPeerCountReply);   - // ------------------------------------------------------------------------ - // Engine API RPC requests natively implemented in the Erigon node backend - // See https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md - - // Validate and possibly execute the payload. - rpc EngineNewPayload(types.ExecutionPayload) returns (EnginePayloadStatus); - - // Update fork choice - rpc EngineForkChoiceUpdated(EngineForkChoiceUpdatedRequest) returns (EngineForkChoiceUpdatedResponse); - - // Fetch Execution Payload using its ID. - rpc EngineGetPayload(EngineGetPayloadRequest) returns (EngineGetPayloadResponse); - - rpc EngineGetPayloadBodiesByHashV1(EngineGetPayloadBodiesByHashV1Request) returns (EngineGetPayloadBodiesV1Response); - - rpc EngineGetPayloadBodiesByRangeV1(EngineGetPayloadBodiesByRangeV1Request) returns (EngineGetPayloadBodiesV1Response); - - // Fetch the blobs bundle using its ID. - rpc EngineGetBlobsBundleV1(EngineGetBlobsBundleRequest) returns (types.BlobsBundleV1); - - // End of Engine API requests - // ------------------------------------------------------------------------ - // Version returns the service version number rpc Version(google.protobuf.Empty) returns (types.VersionReply);   @@ -66,7 +43,12 @@ // Peers collects and returns peers information from all running sentry instances. rpc Peers(google.protobuf.Empty) returns (PeersReply);   + rpc AddPeer(AddPeerRequest) returns (AddPeerReply); + + // PendingBlock returns latest built block. rpc PendingBlock(google.protobuf.Empty) returns (PendingBlockReply); + + rpc BorEvent(BorEventRequest) returns (BorEventReply); }   enum Event { @@ -78,6 +60,7 @@ // client need to close old file descriptors and open new (on new segments), // then server can remove old files NEW_SNAPSHOT = 3; } +   message EtherbaseRequest {}   @@ -91,58 +74,6 @@ message NetPeerCountRequest {}   message NetPeerCountReply { uint64 count = 1; }   - -message EngineGetPayloadRequest { - uint64 payload_id = 1; -} - -message EngineGetBlobsBundleRequest { - uint64 payload_id = 1; -} - -enum EngineStatus { - VALID = 0; - INVALID = 1; - SYNCING = 2; - ACCEPTED = 3; - INVALID_BLOCK_HASH = 4; -} - -message EnginePayloadStatus { - EngineStatus status = 1; - types.H256 latest_valid_hash = 2; - string validation_error = 3; -} - -message EnginePayloadAttributes { - uint32 version = 1; // v1 - no withdrawals, v2 - with withdrawals - uint64 timestamp = 2; - types.H256 prev_randao = 3; - types.H160 suggested_fee_recipient = 4; - repeated types.Withdrawal withdrawals = 5; -} - -message EngineForkChoiceState { - types.H256 head_block_hash = 1; - types.H256 safe_block_hash = 2; - types.H256 finalized_block_hash = 3; -} - -message EngineForkChoiceUpdatedRequest { - EngineForkChoiceState forkchoice_state = 1; - EnginePayloadAttributes payload_attributes = 2; -} - -message EngineForkChoiceUpdatedResponse { - EnginePayloadStatus payload_status = 1; - uint64 payload_id = 2; -} - -message EngineGetPayloadResponse { - types.ExecutionPayload execution_payload = 1; - types.H256 block_value = 2; -} - message ProtocolVersionRequest {}   message ProtocolVersionReply { uint64 id = 1; } @@ -201,6 +132,10 @@ message NodesInfoRequest { uint32 limit = 1; }   +message AddPeerRequest { + string url = 1; +} + message NodesInfoReply { repeated types.NodeInfoReply nodes_info = 1; } @@ -209,6 +144,10 @@ message PeersReply { repeated types.PeerInfo peers = 1; }   +message AddPeerReply { + bool success = 1; +} + message PendingBlockReply { bytes block_rlp = 1; } @@ -220,8 +159,14 @@ message EngineGetPayloadBodiesByRangeV1Request { uint64 start = 1; uint64 count = 2; +} + +message BorEventRequest { + types.H256 bor_tx_hash = 1; }   -message EngineGetPayloadBodiesV1Response { - repeated types.ExecutionPayloadBodyV1 bodies = 1; +message BorEventReply { + bool present = 1; + uint64 block_number = 2; + repeated bytes event_rlps = 3; }
diff --git erigontech/interfaces/remote/kv.proto testinprod-io/erigon-interfaces/remote/kv.proto index de9b2ed40b0688135adf808e456567fcef9b4db8..ffeef00cd8fcd292dba6a17a3b338bdf4774a7cb 100644 --- erigontech/interfaces/remote/kv.proto +++ testinprod-io/erigon-interfaces/remote/kv.proto @@ -11,7 +11,7 @@ //Variables Naming: // ts - TimeStamp // tx - Database Transaction -// txn - Ethereum Transaction (and TxNum - is also number of Etherum Transaction) +// txn - Ethereum Transaction (and TxNum - is also number of Ethereum Transaction) // RoTx - Read-Only Database Transaction // RwTx - Read-Write Database Transaction // k - key @@ -102,14 +102,14 @@ bytes k = 1; bytes v = 2; uint32 cursor_id = 3; // send once after new cursor open uint64 view_id = 4; // return once after tx open. mdbx's tx.ViewID() - id of write transaction in db - uint64 tx_id = 5; // return once after tx open. internal identifier - use it in other methods - to achieve consistant DB view (to read data from same DB tx on server). + uint64 tx_id = 5; // return once after tx open. internal identifier - use it in other methods - to achieve consistent DB view (to read data from same DB tx on server). }   enum Action { STORAGE = 0; // Change only in the storage UPSERT = 1; // Change of balance or nonce (and optionally storage) CODE = 2; // Change of code (and optionally storage) - UPSERT_CODE = 3; // Change in (balance or nonce) and code (and optinally storage) + UPSERT_CODE = 3; // Change in (balance or nonce) and code (and optionally storage) REMOVE = 4; // Account is deleted }   @@ -138,6 +138,8 @@ uint64 state_version_id = 1; // mdbx's tx.ID() - id of write transaction in db - where this changes happened repeated StateChange change_batch = 2; uint64 pending_block_base_fee = 3; // BaseFee of the next block to be produced uint64 block_gas_limit = 4; // GasLimit of the latest block - proxy for the gas limit of the next block to be produced + uint64 finalized_block = 5; + uint64 pending_blob_fee_per_gas = 6; // Base Blob Fee for the next block to be produced }   // StateChange - changes done by 1 block or by 1 unwind @@ -165,7 +167,7 @@ message RangeReq { uint64 tx_id = 1; // returned by .Tx()   - // It's ok to query wide/unlilmited range of data, server will use `pagination params` + // It's ok to query wide/unlimited range of data, server will use `pagination params` // reply by limited batches/pages and client can decide: request next page or not   // query params
diff --git erigontech/interfaces/txpool/mining.proto testinprod-io/erigon-interfaces/txpool/mining.proto index 9e3286d4e06e2def16cdb78c620aad91c59e7b7f..a31d3b7807f4508cf22bb67e0fdc7e5e87c48f83 100644 --- erigontech/interfaces/txpool/mining.proto +++ testinprod-io/erigon-interfaces/txpool/mining.proto @@ -98,6 +98,6 @@ // HashRate returns the current hashrate for local CPU miner and remote miner. rpc HashRate(HashRateRequest) returns (HashRateReply);   - // Mining returns an indication if this node is currently mining and it's mining configuration + // Mining returns an indication if this node is currently mining and its mining configuration rpc Mining(MiningRequest) returns (MiningReply); }
diff --git erigontech/interfaces/types/types.proto testinprod-io/erigon-interfaces/types/types.proto index 732b15cb4a60ec34b7b8e70cda20c95fe4754e10..7a0c30dd3f8dc437023afb076381e4ac5713f16e 100644 --- erigontech/interfaces/types/types.proto +++ testinprod-io/erigon-interfaces/types/types.proto @@ -59,7 +59,7 @@ // ------------------------------------------------------------------------ // Engine API types // See https://github.com/ethereum/execution-apis/blob/main/src/engine message ExecutionPayload { - uint32 version = 1; // v1 - no withdrawals, v2 - with withdrawals, v3 - with excess data gas + uint32 version = 1; // v1 - no withdrawals, v2 - with withdrawals, v3 - with blob gas H256 parent_hash = 2; H160 coinbase = 3; H256 state_root = 4; @@ -75,7 +75,8 @@ H256 base_fee_per_gas = 13; H256 block_hash = 14; repeated bytes transactions = 15; repeated Withdrawal withdrawals = 16; - optional H256 excess_data_gas = 17; + optional uint64 blob_gas_used = 17; + optional uint64 excess_blob_gas = 18; }   message Withdrawal { @@ -86,11 +87,11 @@ uint64 amount = 4; }   message BlobsBundleV1 { - H256 block_hash = 1; // TODO(eip-4844): define a protobuf message for type KZGCommitment - repeated bytes kzgs = 2; + repeated bytes commitments = 1; // TODO(eip-4844): define a protobuf message for type Blob - repeated bytes blobs = 3; + repeated bytes blobs = 2; + repeated bytes proofs = 3; }   // End of Engine API types
diff --git erigontech/interfaces/forkdiff.yaml testinprod-io/erigon-interfaces/forkdiff.yaml new file mode 100644 index 0000000000000000000000000000000000000000..48687856fbd7e95188c1fb5c0d308533a59315db --- /dev/null +++ testinprod-io/erigon-interfaces/forkdiff.yaml @@ -0,0 +1,24 @@ +title: "op-erigon-interfaces" +footer: | + Fork-diff overview of [op-erigon-interfaces](https://github.com/testinprod-io/erigon-interfaces), a fork of [erigon-interfaces](https://github.com/erigontech/interfaces). +base: + name: erigontech/interfaces + url: https://github.com/erigontech/interfaces + hash: e1c4a1a4279ea0d1c74707fc199d69d76ba7594d +fork: + name: testinprod-io/erigon-interfaces + url: https://github.com/testinprod-io/erigon-interfaces + ref: refs/heads/op-erigon +def: + title: "op-erigon-interfaces" + description: | + This is an overview of the changes in [op-erigon-interfaces](https://github.com/testinprod-io/erigon-interfaces), a fork of [erigon-interface](https://github.com/erigontech/interfaces). + sub: + - title: "Protocol Buffer Files" + description: | + op-erigon extends existing gRPC for new RPC definitions and extraneous data that Optimism utilizes. + globs: + - "**/*.proto" +ignore: + - .gitignore + - _docs/* \ No newline at end of file
diff --git erigontech/interfaces/.gitignore testinprod-io/erigon-interfaces/.gitignore index 0d36de15127fdda055ff10924a5d6ec9e47e473f..9e7967d44257018d564eed0c195100b7daa18e1f 100644 --- erigontech/interfaces/.gitignore +++ testinprod-io/erigon-interfaces/.gitignore @@ -2,4 +2,4 @@ .idea/ /target Cargo.lock   -go.work \ No newline at end of file +go.work*
diff --git erigontech/interfaces/_docs/README.md testinprod-io/erigon-interfaces/_docs/README.md index 62eba7ecd3ff7f184a958776c53d55caae6a355e..5d53247af7c194adc2445ad67d38901c6a899660 100644 --- erigontech/interfaces/_docs/README.md +++ testinprod-io/erigon-interfaces/_docs/README.md @@ -8,34 +8,34 @@ # Loosely Coupled Architecture   The node consists of loosely coupled components with well defined "edges" -- protocols that are used between these components.   -Its a reminiscence of [microservices architecture](https://en.wikipedia.org/wiki/Microservices), where each component has clearly defined reponsibilities and interface. Implementation might vary. In case of Erigon, we use gRPC/protobuf definitions, that allows the components to be written in different languages. +It's a reminiscence of [microservices architecture](https://en.wikipedia.org/wiki/Microservices), where each component has clearly defined responsibilities and interface. Implementation might vary. In case of Erigon, we use gRPC/protobuf definitions, that allow the components to be written in different languages.   In our experience, each p2p blockchain node has more or less these components, even when those aren't explicitly set up. In that case we have a highly coupled system of the same components but with more resistance to changes. ## Advantages of loosely coupled architecture   -* Less dependencies between components -- less side-effects of chaging one component is on another. +* Less dependencies between components -- less side-effects of changing one component is on another.   -* Team scalability -- with well specified components, its easy to make sub-teams that work on each component with less coordination overhead. Most cross-team communication is around the interface definition and interpretation. +* Team scalability -- with well specified components, it's easy to make sub-teams that work on each component with less coordination overhead. Most cross-team communication is around the interface definition and interpretation.   * Learning curve reduction -- it is not that easy to find a full-fledged blockchain node developer, but narrowing down the area of responsiblities, makes it easier to both find candidates and coach/mentor the right skillset for them.   -* Innovation and improvements of each layer independently -- for specialized teams for each sub-component, its easier to find some more improvements or optimizations or innovative approaches than in a team that has to keep everything about the node in the head. +* Innovation and improvements of each layer independently -- for specialized teams for each sub-component, it's easier to find some more improvements or optimizations or innovative approaches than in a team that has to keep everything about the node in the head.   -## Designing for upgradeabilty +## Designing for upgradeability   One important part of the design of a node is to make sure that we leave ourselves a room to upgrade it in a simple way.   That means a couple of things: -- protocols for each components should be versioned, to make sure that we can't run inconsistent versions together. [semver](https://semver.org) is a better approach there because it allows to parse even future versions and figure out how compatible they are based on a simple convention; +- protocols for each component should be versioned, to make sure that we can't run inconsistent versions together. [semver](https://semver.org) is a better approach there because it allows to parse even future versions and figure out how compatible they are based on a simple convention;   -- trying to keep compatiblity as much as possible, unless there is a very good reason to break it, we will try to keep it. In practice that means: +- trying to keep compatibility as much as possible, unless there is a very good reason to break it, we will try to keep it. In practice that means: - adding new APIs is safe; - adding new parameters is safe, taking into account that we can always support them missing and revert to the old behaviour; - renaming parameters and methods considered harmful; - - removing paramters and methods considered harmful; + - removing parameters and methods considered harmful; - radically changing the behaviour of the method w/o any changes to the protocol considered harmful;   -Tools for automatic checks about compabilitity are available for Protobuf: https://github.com/bufbuild/buf +Tools for automatic checks about compatibility are available for Protobuf: https://github.com/bufbuild/buf ## Implementation variants   ### Microservices @@ -134,5 +134,5 @@ - [consensus_engine, proto](../consensus_engine/consensus.proto)   ## 6. Downloader   -Downloader component abstracts away the functionality of deliverying some parts of the database using "out of band" protocols like BitTorrent, +Downloader component abstracts away the functionality of delivering some parts of the database using "out of band" protocols like BitTorrent, IPFS, Swarm and others.
diff --git erigontech/interfaces/_docs/staged-sync.md testinprod-io/erigon-interfaces/_docs/staged-sync.md index 88a9874fd86d49a67018126c4e3f09deb7a36447..52205cf908618dcf31ac09d046989a0ce661e8d7 100644 --- erigontech/interfaces/_docs/staged-sync.md +++ testinprod-io/erigon-interfaces/_docs/staged-sync.md @@ -25,7 +25,7 @@ Only ID and progress functions are required.   Both progress and unwind functions can have side-effects. In practice, usually only progress do (downloader interaction).   -Each function (progress, unwind, prune) have **input** DB buckets and **output** DB buckets. That allows to build a dependency graph and run them in order. +Each function (progress, unwind, prune) has **input** DB buckets and **output** DB buckets. That allows to build a dependency graph and run them in order.   ![](./stages-ordering.png)   @@ -51,7 +51,7 @@ That allows to group similar operations together and optimize each stage for throughput. Also, some stages, like the commitment stage, require way less hashes computation on genesis sync.   That also allows DB inserts optimisations, see next part.   -### ETL and optimial DB inserts +### ETL and optimal DB inserts   ![](./stages-etl.png)   @@ -61,7 +61,7 @@ That all is called **write amplification**. The more random stuff you insert into a DB, the more expensive it is to insert it.   Luckily, if we insert keys in a sorted order, this effect is not there, we fill pages one by one.   -That is where our ETL framework comes to the rescue. When batch processing data, instead of wrting it directly to a database, we first extract it to a temp folder (could be in ram if fits). When extraction happens, we generate the keys for insertion. Then, we load data from these data files in a sorted manner using a heap. That way, the keys are always inserted sorted. +That is where our ETL framework comes to the rescue. When batch processing data, instead of writing it directly to a database, we first extract it to a temp folder (could be in ram if fits). When extraction happens, we generate the keys for insertion. Then, we load data from these data files in a sorted manner using a heap. That way, the keys are always inserted sorted.   This approach also allows us to avoid overwrites in certain scenarios, because we can specify the right strategy on loading data: do we want to keep only the latest data, convert it into a list or anything else.