diff --git a/docs/fairy_core/integration/01_overview.md b/docs/fairy_core/integration/01_overview.md index 8bbffd6c..4cf6fea8 100644 --- a/docs/fairy_core/integration/01_overview.md +++ b/docs/fairy_core/integration/01_overview.md @@ -3,11 +3,11 @@ This section deals with integrating any chain with FairyRing chain. A chain that leverages the IBE functionality of FairyRing for encrypting, decrypting and executing transactions (the Destination Chain). All Destination Chains require the following to leverage the FairyRing functionalities: 1. A module to store encrypted transactions and queue them based on their target height. The module should also have the functionality to decrypt and execute said transactions when the target height is reached. -2. A functionality to fetch generated aggregated keyshares fast and reliably from the FairyRing chain. These aggrgated keyshares act as the decryption key for the encrypted transactions. +2. A functionality to fetch generated aggregated keyshares fast and reliably from the FairyRing chain. These aggregated keyshares act as the decryption key for the encrypted transactions. All encrypted transactions are executed on the destination chain itself. The target height for execution is that of the Fairyring chain. This is necessary since aggregated keyshares are generated per block of FairyRing and does not have any bearing with the height of the destination chain(s). -For now, the same aggregated keyshare generated by FairyRing is used by all the destination chains to decrypt their transactions. This is subject to channge, where a set of aggregated keyshares may be generated by FairyRing and destination chains may require one or more of these to decrypt their transactions. +For now, the same aggregated keyshare generated by FairyRing is used by all the destination chains to decrypt their transactions. This is subject to change, where a set of aggregated keyshares may be generated by FairyRing and destination chains may require one or more of these to decrypt their transactions. To make integration easier for destination chains, FairBlock provides solutions to both the requirements: diff --git a/docs/fairy_core/integration/04_pep_module.md b/docs/fairy_core/integration/04_pep_module.md index aa584af4..34f2babe 100644 --- a/docs/fairy_core/integration/04_pep_module.md +++ b/docs/fairy_core/integration/04_pep_module.md @@ -7,7 +7,7 @@ The PEP module stands for Pre-Execution Privacy. It has the following capabiliti 1. Accept encrypted txs from users: `SubmitEncryptedTx` 2. Verify and accept aggregated Keyshares from FairyPort: `CreateAggregatedKeyShare` 3. Queue encrypted Txs in its store indexed by their target height -4. Decrypt and Execute the encrypted Txs automatically whenever the respective aggrgated keyshare becomes available +4. Decrypt and Execute the encrypted Txs automatically whenever the respective aggregated keyshare becomes available 5. Keep pubkeys in its store to verify the submitted Aggregated Keyshares 6. Automatically use the queued keys when the active key expires 7. IBC functionality to query for pubkeys from FairyRing chain and update them (requires a relayer) diff --git a/docs/fairy_core/key_concepts/functionalities/01_pubkey.md b/docs/fairy_core/key_concepts/functionalities/01_pubkey.md index 3790778d..d9c4e72b 100644 --- a/docs/fairy_core/key_concepts/functionalities/01_pubkey.md +++ b/docs/fairy_core/key_concepts/functionalities/01_pubkey.md @@ -19,11 +19,11 @@ The default expiry duration is decided by the `KeyExpiry` param of the `KeyShare ## Adding a New PubKey -The procedure for adding new Public Keys is different for the FairyRing chain and the destination chains. Whereas for the FairyRing chain, new keys are added via transations from verified addresses to the chain, the addition of pubkeys to destination chains is purely dependent on any change in pubkeys in the FairyRing chain and this information is fetched via IBC. +The procedure for adding new Public Keys is different for the FairyRing chain and the destination chains. Whereas for the FairyRing chain, new keys are added via transactions from verified addresses to the chain, the addition of pubkeys to destination chains is purely dependent on any change in pubkeys in the FairyRing chain and this information is fetched via IBC. ### Adding Keys to Destination Chains -Destination chains can only recieve pubkeys from the FairyRing chain via IBC. The PEP module, which is implemented by both FairyRing chain and destination chain, is an IBC enabled module. The Destination chain's PEP module becomes the A-end while the PEP module of the FairyRing chain becomes the B-end. At the end of every block, the PEP module of the A-end makes a call to the B-end to get the latest pubkeys. +Destination chains can only receive pubkeys from the FairyRing chain via IBC. The PEP module, which is implemented by both FairyRing chain and destination chain, is an IBC enabled module. The Destination chain's PEP module becomes the A-end while the PEP module of the FairyRing chain becomes the B-end. At the end of every block, the PEP module of the A-end makes a call to the B-end to get the latest pubkeys. Note the following: diff --git a/docs/fairy_core/modules/02_pep_module.md b/docs/fairy_core/modules/02_pep_module.md index 6b03cf49..71d71fa0 100644 --- a/docs/fairy_core/modules/02_pep_module.md +++ b/docs/fairy_core/modules/02_pep_module.md @@ -1,5 +1,5 @@ # PEP Module -The Pre-Execution Privacy (PEP) module is responsible for accepting encrypted transactions from users, storing them in its state ordered by their target height, accepting aggregated keyshares and finally executing the encrytpted transactions at their respective target heights. +The Pre-Execution Privacy (PEP) module is responsible for accepting encrypted transactions from users, storing them in its state ordered by their target height, accepting aggregated keyshares and finally executing the encrypted transactions at their respective target heights. Refer to the [PEP Specifications](https://github.com/FairBlock/fairyring/blob/audit/x/pep/specs/01_overview.md) for details on the working of the PEP module. diff --git a/docs/validator/02_keyshare_submission.md b/docs/validator/02_keyshare_submission.md index f647a725..25381082 100644 --- a/docs/validator/02_keyshare_submission.md +++ b/docs/validator/02_keyshare_submission.md @@ -1,6 +1,6 @@ # Generating and Submitting KeyShares -Validitors on FairyRing have two main purposes: +Validators on FairyRing have two main purposes: - Participate in consensus to generate blocks. This functionality is the same as with any other chain on Cosmos. - Submit Keyshares at every block diff --git a/x/keyshare/specs/06_begin_block.md b/x/keyshare/specs/06_begin_block.md index f3f30847..01f771a6 100644 --- a/x/keyshare/specs/06_begin_block.md +++ b/x/keyshare/specs/06_begin_block.md @@ -10,7 +10,7 @@ The Begin block of KeyShare module does the following three things: ## Update Registered Validator Set -Validators who are not bonded (due to missing blocks, starting unbonding or being tombstoned) are not eligible for submitting keyshares to the module. The will be removed in the begining of the block and cannot submit their keyshares anymore. +Validators who are not bonded (due to missing blocks, starting unbonding or being tombstoned) are not eligible for submitting keyshares to the module. The will be removed in the beginning of the block and cannot submit their keyshares anymore. ```go for _, eachValidator := range validators { @@ -26,7 +26,7 @@ for _, eachValidator := range validators { ## Active Key Expiry -The status of the Active PubKey is checked at the begining of every block. If the Key is found to be expired, it is replaced by the queued key. In case there is no queued key, the active key is simply removed. No Keyshares can be submitted till a new Active Key is assigned. +The status of the Active PubKey is checked at the beginning of every block. If the Key is found to be expired, it is replaced by the queued key. In case there is no queued key, the active key is simply removed. No Keyshares can be submitted till a new Active Key is assigned. ```go ak, foundAk := am.keeper.GetActivePubKey(ctx) diff --git a/x/pep/specs/02_concepts.md b/x/pep/specs/02_concepts.md index e5efa3bd..05a203e7 100644 --- a/x/pep/specs/02_concepts.md +++ b/x/pep/specs/02_concepts.md @@ -1,10 +1,10 @@ # PEP Concepts -The PEP module leverages the power of IBE to decrypt transactions and process them at the desired height. Due to this, it is impossible to know the contents of a transaction before the target height is reached. On Reaching the target height, the encrypted transactions for that height are the first to be executed befor any mempool transactions. This completely removes any chance of these transactions being frontrun. +The PEP module leverages the power of IBE to decrypt transactions and process them at the desired height. Due to this, it is impossible to know the contents of a transaction before the target height is reached. On Reaching the target height, the encrypted transactions for that height are the first to be executed before any mempool transactions. This completely removes any chance of these transactions being frontrun. -The PEP module gets an Active Public Key and a Queued Public Key from the FairyRing Chain via IBC. Hence all destination chains that wish to use the PEP module must run a realyer and connect their chain to the FairyRing chain. Users on the destination chain can then encrypt the transactions using these public keys and send them to their corresponding chains. +The PEP module gets an Active Public Key and a Queued Public Key from the FairyRing Chain via IBC. Hence all destination chains that wish to use the PEP module must run a relayer and connect their chain to the FairyRing chain. Users on the destination chain can then encrypt the transactions using these public keys and send them to their corresponding chains. -Encrypted Txs are not executed immediately. Instead, they are stored in the state of the PEP module indexed by their target height. When the target height is reached, and the aggregated keyshares for the target height become avaialble, these transactions are automatically decrypted and executed before all other mempool transactions. +Encrypted Txs are not executed immediately. Instead, they are stored in the state of the PEP module indexed by their target height. When the target height is reached, and the aggregated keyshares for the target height become available, these transactions are automatically decrypted and executed before all other mempool transactions. To get the latest aggregated keyshare from the FairyRing chain, some kind of an Inter-chain Communication is required. However, the IBC which is built on the ICS standards, does not work in this specific case. This is mainly due to the vector commitment associated with IBC which may take some time. From tweaking around with relayers and block generation times of both chains, it seems like there is an average delay of 3-5 blocks between an IC request being sent and the response being received. However, this would mean that although aggregated shares are already released by the FairyRing chain, it takes 3-5 blocks for it to be registered on the destination chain. This gives malicious users a decent window to frontrun the encrypted transactions as they will not be executed till the aggregated keyshare is registered on-chain. diff --git a/x/pep/specs/04_state_transition.md b/x/pep/specs/04_state_transition.md index 20d46271..ada42128 100644 --- a/x/pep/specs/04_state_transition.md +++ b/x/pep/specs/04_state_transition.md @@ -65,7 +65,7 @@ func (am AppModule) EndBlock(ctx sdk.Context, _ abci.RequestEndBlock) []abci.Val ## AggregatedKeyShare -This state is modified when a transaction is made (normally by the FairyPort service) to register a new aggregated keyshare generated in the FairyRing chain. Unlike other transactions, this transaction is not normally executed. Instead, at the beign block of the PEP module, transactions with message type `MsgCreateAggregatedKeyShare` are searched for in the mempool. If found, these messages are then automatically executed. +This state is modified when a transaction is made (normally by the FairyPort service) to register a new aggregated keyshare generated in the FairyRing chain. Unlike other transactions, this transaction is not normally executed. Instead, at the beginning block of the PEP module, transactions with message type `MsgCreateAggregatedKeyShare` are searched for in the mempool. If found, these messages are then automatically executed. Ref: diff --git a/x/pep/specs/06_begin_block.md b/x/pep/specs/06_begin_block.md index 3fb95cab..21da2e39 100644 --- a/x/pep/specs/06_begin_block.md +++ b/x/pep/specs/06_begin_block.md @@ -29,7 +29,7 @@ if utxs != nil { --- -## Decrypting Encryted Transactions +## Decrypting Encrypted Transactions The Pep Begin block fetches the last target height that it executed and the latest height for which aggregated keyshares are available. It then fetches all encrypted transactions in this range, decrypt them one by one and execute them. For example, if the last executed height was 100 and the latest aggregated keyshare has a height of 105, it feches all encrypted transactions that have a target height of 100-105.