Update API documentation (#396)

Layr-Labs · Mar 25, 2024 · 95549d8 · 95549d8
1 parent c1b1146
commit 95549d8
Show file tree

Hide file tree

Showing 4 changed files with 118 additions and 109 deletions.
diff --git a/api/docs/churner.md b/api/docs/churner.md
@@ -31,7 +31,9 @@
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | signature_with_salt_and_expiry | [SignatureWithSaltAndExpiry](#churner-SignatureWithSaltAndExpiry) |  | The signature signed by the Churner. |
-| operators_to_churn | [OperatorToChurn](#churner-OperatorToChurn) | repeated | A list of existing operators that get churned out. Note: it&#39;s possible an operator gets churned out just for one or more quorums (rather than entirely churned out for all quorums). |
+| operators_to_churn | [OperatorToChurn](#churner-OperatorToChurn) | repeated | A list of existing operators that get churned out. This list will contain all quorums specified in the ChurnRequest even if some quorums may not have any churned out operators. If a quorum has available space, OperatorToChurn object will contain the quorum ID and empty operator and pubkey. The smart contract should only churn out the operators for quorums that are full.
+
+For example, if the ChurnRequest specifies quorums 0 and 1 where quorum 0 is full and quorum 1 has available space, the ChurnReply will contain two OperatorToChurn objects with the respective quorums. OperatorToChurn for quorum 0 will contain the operator to churn out and OperatorToChurn for quorum 1 will contain empty operator (zero address) and pubkey. The smart contract should only churn out the operators for quorum 0 because quorum 1 has available space without having any operators churned. Note: it&#39;s possible an operator gets churned out just for one or more quorums (rather than entirely churned out for all quorums). |
 
 
 
@@ -51,7 +53,7 @@
 | operator_to_register_pubkey_g2 | [bytes](#bytes) |  |  |
 | operator_request_signature | [bytes](#bytes) |  | The operator&#39;s BLS signature signed on the keccak256 hash of concat(&#34;ChurnRequest&#34;, operator address, g1, g2, salt). |
 | salt | [bytes](#bytes) |  | The salt used as part of the message to sign on for operator_request_signature. |
-| quorum_ids | [uint32](#uint32) | repeated | The quorums to register for. Note: - If any of the quorum here has already been registered, this entire request will fail to proceed. - If any of the quorum fails to register, this entire request will fail. The IDs must be in range [0, 255]. |
+| quorum_ids | [uint32](#uint32) | repeated | The quorums to register for. Note: - If any of the quorum here has already been registered, this entire request will fail to proceed. - If any of the quorum fails to register, this entire request will fail. - Regardless of whether the specified quorums are full or not, the Churner will return parameters for all quorums specified here. The smart contract will determine whether it needs to churn out existing operators based on whether the quorums have available space. The IDs must be in range [0, 254]. |
 
 
 

diff --git a/api/docs/disperser.md b/api/docs/disperser.md
@@ -3,9 +3,6 @@
 
 ## Table of Contents
 
-- [common/common.proto](#common_common-proto)
-    - [G1Commitment](#common-G1Commitment)
-
 - [disperser/disperser.proto](#disperser_disperser-proto)
     - [AuthenticatedReply](#disperser-AuthenticatedReply)
     - [AuthenticatedRequest](#disperser-AuthenticatedRequest)
@@ -23,48 +20,18 @@
     - [DisperseBlobRequest](#disperser-DisperseBlobRequest)
     - [RetrieveBlobReply](#disperser-RetrieveBlobReply)
     - [RetrieveBlobRequest](#disperser-RetrieveBlobRequest)
-    - [SecurityParams](#disperser-SecurityParams)
 
     - [BlobStatus](#disperser-BlobStatus)
 
     - [Disperser](#disperser-Disperser)
 
+- [common/common.proto](#common_common-proto)
+    - [G1Commitment](#common-G1Commitment)
+
 - [Scalar Value Types](#scalar-value-types)
 
 
 
-<a name="common_common-proto"></a>
-<p align="right"><a href="#top">Top</a></p>
-
-## common/common.proto
-
-
-
-<a name="common-G1Commitment"></a>
-
-### G1Commitment
-
-
-
-| Field | Type | Label | Description |
-| ----- | ---- | ----- | ----------- |
-| x | [bytes](#bytes) |  | The X coordinate of the KZG commitment. This is the raw byte representation of the field element. |
-| y | [bytes](#bytes) |  | The Y coordinate of the KZG commitment. This is the raw byte representation of the field element. |
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 <a name="disperser_disperser-proto"></a>
 <p align="right"><a href="#top">Top</a></p>
 
@@ -220,8 +187,8 @@ BlobInfo contains information needed to confirm the blob against the EigenDA con
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | quorum_number | [uint32](#uint32) |  | The ID of the quorum. |
-| adversary_threshold_percentage | [uint32](#uint32) |  | Same as SecurityParams.adversary_threshold. |
-| quorum_threshold_percentage | [uint32](#uint32) |  | Same as SecurityParams.quorum_threshold. |
+| adversary_threshold_percentage | [uint32](#uint32) |  | The max percentage of stake within the quorum that can be held by or delegated to adversarial operators. Currently, this and the next parameter are standardized across the quorum using values read from the EigenDA contracts. |
+| confirmation_threshold_percentage | [uint32](#uint32) |  | The min percentage of stake that must attest in order to consider the dispersal is successful. |
 | chunk_length | [uint32](#uint32) |  | The length of each chunk. |
 
 
@@ -304,7 +271,7 @@ BlobStatusRequest is used to query the status of a blob.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | data | [bytes](#bytes) |  | The data to be dispersed. The size of data must be &lt;= 2MiB. |
-| security_params | [SecurityParams](#disperser-SecurityParams) | repeated | Security parameters allowing clients to customize the safety (via adversary threshold) and liveness (via quorum threshold). Clients can define one SecurityParams per quorum, and specify multiple quorums. The disperser will ensure that the encoded blobs for each quorum are all processed within the same batch. |
+| custom_quorum_numbers | [uint32](#uint32) | repeated | The quorums to which the blob will be sent, in addition to the required quorums which are configured on the EigenDA smart contract. If required quorums are included here, an error will be returned. The disperser will ensure that the encoded blobs for each quorum are all processed within the same batch. |
 | account_id | [string](#string) |  | The account ID of the client. This should be a hex-encoded string of the ECSDA public key corresponding to the key used by the client to sign the BlobAuthHeader. |
 
 
@@ -342,33 +309,6 @@ RetrieveBlobRequest contains parameters to retrieve the blob.
 
 
 
-
-<a name="disperser-SecurityParams"></a>
-
-### SecurityParams
-SecurityParams contains the security parameters for a given quorum.
-
-
-| Field | Type | Label | Description |
-| ----- | ---- | ----- | ----------- |
-| quorum_id | [uint32](#uint32) |  | The ID of the quorum. The quorum must be already registered on EigenLayer. The ID must be in range [0, 254]. |
-| adversary_threshold | [uint32](#uint32) |  | The max percentage of stake within the quorum that can be held by or delegated to adversarial operators.
-
-Clients use this to customize the trust assumption (safety).
-
-Requires: 1 &lt;= adversary_threshold &lt; 100 |
-| quorum_threshold | [uint32](#uint32) |  | The min percentage of stake that must attest in order to consider the dispersal is successful.
-
-Clients use this to customize liveness requirement. The higher this number, the more operators may need to be up for attesting the blob, so the chance the dispersal request to fail may be higher (liveness for dispersal).
-
-Requires: 1 &lt;= quorum_threshld &lt;= 100 quorum_threshld &gt; adversary_threshold &#43; 10.
-
-Note: The adversary_threshold and quorum_threshold will directly influence the cost of encoding for the blob to be dispersed, roughly by a factor of 100 / (quorum_threshold - adversary_threshold). See the spec for more details: https://github.com/Layr-Labs/eigenda/blob/master/docs/spec/protocol-modules/storage/overview.md Currently it&#39;s required that the difference must be at least 10. |
-
-
-
-
-
 
 
 
@@ -384,7 +324,7 @@ Note: The adversary_threshold and quorum_threshold will directly influence the c
 | CONFIRMED | 2 | CONFIRMED means that the blob has been dispersed to DA Nodes and the dispersed batch containing the blob has been confirmed onchain |
 | FAILED | 3 | FAILED means that the blob has failed permanently (for reasons other than insufficient signatures, which is a separate state) |
 | FINALIZED | 4 | FINALIZED means that the block containing the blob&#39;s confirmation transaction has been finalized on Ethereum |
-| INSUFFICIENT_SIGNATURES | 5 | INSUFFICIENT_SIGNATURES means that the quorum threshold for the blob was not met for at least one quorum. |
+| INSUFFICIENT_SIGNATURES | 5 | INSUFFICIENT_SIGNATURES means that the confirmation threshold for the blob was not met for at least one quorum. |
 
 
 
@@ -408,6 +348,38 @@ Disperser defines the public APIs for dispersing blobs.
 
 
 
+<a name="common_common-proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## common/common.proto
+
+
+
+<a name="common-G1Commitment"></a>
+
+### G1Commitment
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| x | [bytes](#bytes) |  | The X coordinate of the KZG commitment. This is the raw byte representation of the field element. |
+| y | [bytes](#bytes) |  | The Y coordinate of the KZG commitment. This is the raw byte representation of the field element. |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 ## Scalar Value Types
 
 | .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |

diff --git a/api/docs/node.md b/api/docs/node.md
@@ -3,9 +3,6 @@
 
 ## Table of Contents
 
-- [common/common.proto](#common_common-proto)
-    - [G1Commitment](#common-G1Commitment)
-
 - [node/node.proto](#node_node-proto)
     - [BatchHeader](#node-BatchHeader)
     - [Blob](#node-Blob)
@@ -24,42 +21,13 @@
     - [Dispersal](#node-Dispersal)
     - [Retrieval](#node-Retrieval)
 
+- [common/common.proto](#common_common-proto)
+    - [G1Commitment](#common-G1Commitment)
+
 - [Scalar Value Types](#scalar-value-types)
 
 
 
-<a name="common_common-proto"></a>
-<p align="right"><a href="#top">Top</a></p>
-
-## common/common.proto
-
-
-
-<a name="common-G1Commitment"></a>
-
-### G1Commitment
-
-
-
-| Field | Type | Label | Description |
-| ----- | ---- | ----- | ----------- |
-| x | [bytes](#bytes) |  | The X coordinate of the KZG commitment. This is the raw byte representation of the field element. |
-| y | [bytes](#bytes) |  | The Y coordinate of the KZG commitment. This is the raw byte representation of the field element. |
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 <a name="node_node-proto"></a>
 <p align="right"><a href="#top">Top</a></p>
 
@@ -97,7 +65,7 @@ single operator node.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | header | [BlobHeader](#node-BlobHeader) |  | Which (original) blob this is for. |
-| bundles | [Bundle](#node-Bundle) | repeated | Each bundle contains all chunks for a single quorum of the blob. The number of bundles must be equal to the total number of quorums associated with the blob, and the ordering must be the same as BlobHeader.quorum_headers. |
+| bundles | [Bundle](#node-Bundle) | repeated | Each bundle contains all chunks for a single quorum of the blob. The number of bundles must be equal to the total number of quorums associated with the blob, and the ordering must be the same as BlobHeader.quorum_headers. Note: an operator may be in some but not all of the quorums; in that case the bundle corresponding to that quorum will be empty. |
 
 
 
@@ -135,7 +103,7 @@ api/proto/disperser/disperser.proto
 | ----- | ---- | ----- | ----------- |
 | quorum_id | [uint32](#uint32) |  |  |
 | adversary_threshold | [uint32](#uint32) |  |  |
-| quorum_threshold | [uint32](#uint32) |  |  |
+| confirmation_threshold | [uint32](#uint32) |  |  |
 | chunk_length | [uint32](#uint32) |  |  |
 | ratelimit | [uint32](#uint32) |  |  |
 
@@ -320,6 +288,38 @@ See RetrieveChunksRequest for documentation of each parameter of GetBlobHeaderRe
 
 
 
+<a name="common_common-proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## common/common.proto
+
+
+
+<a name="common-G1Commitment"></a>
+
+### G1Commitment
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| x | [bytes](#bytes) |  | The X coordinate of the KZG commitment. This is the raw byte representation of the field element. |
+| y | [bytes](#bytes) |  | The Y coordinate of the KZG commitment. This is the raw byte representation of the field element. |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 ## Scalar Value Types
 
 | .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |

diff --git a/api/docs/retriever.md b/api/docs/retriever.md
@@ -3,20 +3,23 @@
 
 ## Table of Contents
 
-- [retriever.proto](#retriever-proto)
+- [retriever/retriever.proto](#retriever_retriever-proto)
     - [BlobReply](#retriever-BlobReply)
     - [BlobRequest](#retriever-BlobRequest)
 
     - [Retriever](#retriever-Retriever)
 
+- [common/common.proto](#common_common-proto)
+    - [G1Commitment](#common-G1Commitment)
+
 - [Scalar Value Types](#scalar-value-types)
 
 
 
-<a name="retriever-proto"></a>
+<a name="retriever_retriever-proto"></a>
 <p align="right"><a href="#top">Top</a></p>
 
-## retriever.proto
+## retriever/retriever.proto
 
 
 
@@ -84,6 +87,38 @@ worse cost and performance.
 
 
 
+<a name="common_common-proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## common/common.proto
+
+
+
+<a name="common-G1Commitment"></a>
+
+### G1Commitment
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| x | [bytes](#bytes) |  | The X coordinate of the KZG commitment. This is the raw byte representation of the field element. |
+| y | [bytes](#bytes) |  | The Y coordinate of the KZG commitment. This is the raw byte representation of the field element. |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 ## Scalar Value Types
 
 | .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |