Update Solidity API docs #36
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| # Random Beacon API | ||
|
|
||
| You can learn about APIs of contracts related to the Random Beacon under the | ||
| following links: | ||
|
|
||
| [AltBn128](./generated-docs/libraries/AltBn128.md) | ||
|
There was a problem hiding this comment. Wouldn't it be better to have them as a bullet list? There was a problem hiding this comment. Same question to all |
||
|
|
||
| [BeaconAuthorization](./generated-docs/libraries/BeaconAuthorization.md) | ||
|
|
||
| [BeaconDkg](./generated-docs/libraries/BeaconDkg.md) | ||
|
|
||
| [BeaconDkgValidator](./generated-docs/BeaconDkgValidator.md) | ||
|
|
||
| [BeaconInactivity](./generated-docs/libraries/BeaconInactivity.md) | ||
|
|
||
| [BLS](./generated-docs/libraries/BLS.md) | ||
|
|
||
| [BytesLib](./generated-docs/libraries/BytesLib.md) | ||
|
|
||
| [Callback](./generated-docs/libraries/Callback.md) | ||
|
|
||
| [Governable](./generated-docs/Governable.md) | ||
|
|
||
| [Groups](./generated-docs/libraries/Groups.md) | ||
|
|
||
| [IRandomBeacon](./generated-docs/api/IRandomBeacon.md) | ||
|
|
||
| [IRandomBeaconConsumer](./generated-docs/api/IRandomBeaconConsumer.md) | ||
|
|
||
| [ModUtils](./generated-docs/libraries/ModUtils.md) | ||
|
|
||
| [RandomBeacon](./generated-docs/RandomBeacon.md) | ||
|
|
||
| [RandomBeaconChaosnet](./generated-docs/RandomBeaconChaosnet.md) | ||
|
|
||
| [RandomBeaconGovernance](./generated-docs/RandomBeaconGovernance.md) | ||
|
|
||
| [Reimbursable](./generated-docs/Reimbursable.md) | ||
|
|
||
| [ReimbursementPool](./generated-docs/ReimbursementPool.md) | ||
|
|
||
| [Relay](./generated-docs/libraries/Relay.md) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,175 @@ | ||
| # Solidity API | ||
|
|
||
| ## BeaconDkgValidator | ||
|
|
||
| DKGValidator allows performing a full validation of DKG result, | ||
| including checking the format of fields in the result, declared | ||
| selected group members, and signatures of operators supporting the | ||
| result. The operator submitting the result should perform the | ||
| validation using a free contract call before submitting the result | ||
| to ensure their result is valid and can not be challenged. All other | ||
| network operators should perform validation of the submitted result | ||
| using a free contract call and challenge the result if the | ||
| validation fails. | ||
|
|
||
| ### groupSize | ||
|
|
||
| ```solidity | ||
| uint256 groupSize | ||
| ``` | ||
|
|
||
| Size of a group in the threshold relay. | ||
|
|
||
| ### groupThreshold | ||
|
|
||
| ```solidity | ||
| uint256 groupThreshold | ||
| ``` | ||
|
|
||
| The minimum number of group members needed to interact according to | ||
| the protocol to produce a relay entry. The adversary can not learn | ||
| anything about the key as long as it does not break into | ||
| groupThreshold+1 of members. | ||
|
|
||
| ### activeThreshold | ||
|
|
||
| ```solidity | ||
| uint256 activeThreshold | ||
| ``` | ||
|
|
||
| The minimum number of active and properly behaving group members | ||
| during the DKG needed to accept the result. This number is higher | ||
| than `groupThreshold` to keep a safety margin for members becoming | ||
| inactive after DKG so that the group can still produce a relay | ||
| entry. | ||
|
|
||
| ### signatureByteSize | ||
|
|
||
| ```solidity | ||
| uint256 signatureByteSize | ||
| ``` | ||
|
|
||
| Size in bytes of a single signature produced by operator supporting | ||
| DKG result. | ||
|
|
||
| ### sortitionPool | ||
|
|
||
| ```solidity | ||
| contract SortitionPool sortitionPool | ||
| ``` | ||
|
|
||
| ### constructor | ||
|
|
||
| ```solidity | ||
| constructor(contract SortitionPool _sortitionPool) public | ||
| ``` | ||
|
|
||
| ### validate | ||
|
|
||
| ```solidity | ||
| function validate(struct BeaconDkg.Result result, uint256 seed, uint256 startBlock) external view returns (bool isValid, string errorMsg) | ||
| ``` | ||
|
|
||
| Performs a full validation of DKG result, including checking the | ||
| format of fields in the result, declared selected group members, | ||
| and signatures of operators supporting the result. | ||
|
|
||
| #### Parameters | ||
|
|
||
| | Name | Type | Description | | ||
| | ---- | ---- | ----------- | | ||
| | result | struct BeaconDkg.Result | | | ||
| | seed | uint256 | seed used to start the DKG and select group members | | ||
| | startBlock | uint256 | DKG start block | | ||
|
|
||
| #### Return Values | ||
|
|
||
| | Name | Type | Description | | ||
| | ---- | ---- | ----------- | | ||
| | isValid | bool | true if the result is valid, false otherwise | | ||
| | errorMsg | string | validation error message; empty for a valid result | | ||
|
|
||
| ### validateFields | ||
|
|
||
| ```solidity | ||
| function validateFields(struct BeaconDkg.Result result) public pure returns (bool isValid, string errorMsg) | ||
| ``` | ||
|
|
||
| Performs a static validation of DKG result fields: lengths, | ||
| ranges, and order of arrays. | ||
|
|
||
| #### Return Values | ||
|
|
||
| | Name | Type | Description | | ||
| | ---- | ---- | ----------- | | ||
| | isValid | bool | true if the result is valid, false otherwise | | ||
| | errorMsg | string | validation error message; empty for a valid result | | ||
|
|
||
| ### validateGroupMembers | ||
|
|
||
| ```solidity | ||
| function validateGroupMembers(struct BeaconDkg.Result result, uint256 seed) public view returns (bool) | ||
| ``` | ||
|
|
||
| Performs validation of group members as declared in DKG | ||
| result against group members selected by the sortition pool. | ||
|
|
||
| #### Parameters | ||
|
|
||
| | Name | Type | Description | | ||
| | ---- | ---- | ----------- | | ||
| | result | struct BeaconDkg.Result | | | ||
| | seed | uint256 | seed used to start the DKG and select group members | | ||
|
|
||
| #### Return Values | ||
|
|
||
| | Name | Type | Description | | ||
| | ---- | ---- | ----------- | | ||
| | [0] | bool | true if group members matches; false otherwise | | ||
|
|
||
| ### validateSignatures | ||
|
|
||
| ```solidity | ||
| function validateSignatures(struct BeaconDkg.Result result, uint256 startBlock) public view returns (bool) | ||
| ``` | ||
|
|
||
| Performs validation of signatures supplied in DKG result. | ||
| Note that this function does not check if addresses which | ||
| supplied signatures supporting the result are the ones selected | ||
| to the group by sortition pool. This function should be used | ||
| together with `validateGroupMembers`. | ||
|
|
||
| #### Parameters | ||
|
|
||
| | Name | Type | Description | | ||
| | ---- | ---- | ----------- | | ||
| | result | struct BeaconDkg.Result | | | ||
| | startBlock | uint256 | DKG start block | | ||
|
|
||
| #### Return Values | ||
|
|
||
| | Name | Type | Description | | ||
| | ---- | ---- | ----------- | | ||
| | [0] | bool | true if group members matches; false otherwise | | ||
|
|
||
| ### validateMembersHash | ||
|
|
||
| ```solidity | ||
| function validateMembersHash(struct BeaconDkg.Result result) public pure returns (bool) | ||
| ``` | ||
|
|
||
| Performs validation of hashed group members that actively took | ||
| part in DKG. | ||
|
|
||
| #### Parameters | ||
|
|
||
| | Name | Type | Description | | ||
| | ---- | ---- | ----------- | | ||
| | result | struct BeaconDkg.Result | DKG result | | ||
|
|
||
| #### Return Values | ||
|
|
||
| | Name | Type | Description | | ||
| | ---- | ---- | ----------- | | ||
| | [0] | bool | true if result's group members hash matches with the one that is challenged. | | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| # Solidity API | ||
|
|
||
| ## Governable | ||
|
|
||
| Governable contract. | ||
|
|
||
| A constructor is not defined, which makes the contract compatible with | ||
| upgradable proxies. This requires calling explicitly `_transferGovernance` | ||
| function in a child contract. | ||
|
|
||
| ### governance | ||
|
|
||
| ```solidity | ||
| address governance | ||
| ``` | ||
|
|
||
| ### GovernanceTransferred | ||
|
|
||
| ```solidity | ||
| event GovernanceTransferred(address oldGovernance, address newGovernance) | ||
| ``` | ||
|
|
||
| ### onlyGovernance | ||
|
|
||
| ```solidity | ||
| modifier onlyGovernance() | ||
| ``` | ||
|
|
||
| ### transferGovernance | ||
|
|
||
| ```solidity | ||
| function transferGovernance(address newGovernance) external virtual | ||
| ``` | ||
|
|
||
| Transfers governance of the contract to `newGovernance`. | ||
|
|
||
| ### _transferGovernance | ||
|
|
||
| ```solidity | ||
| function _transferGovernance(address newGovernance) internal virtual | ||
| ``` | ||
|
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This copy could be a bit better. We could point the reader to the repository, say that the code documentation was generated automatically based on the docs in the code.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
#37