Merge pull request #46 from iden3/chore/PID-1175-fix-audit-notes

PID-1175 Fix audit notes

mkdocs/docs/contracts/state.md

@@ -1,17 +1,17 @@
 ### State Contract
 
-[**StateV2.sol - Github**](https://github.com/iden3/contracts/blob/master/contracts/state/StateV2.sol)
+[**State.sol - Github**](https://github.com/iden3/contracts/blob/master/contracts/state/State.sol)
 
 The State Contract stores the [Global Identity State Tree](../protocol/spec.md#gist-new). The GIST State represents a snapshot of the states of all the identities operating in the system. The design of the State Contract allows identities to authenticate themselves using [Identity Profiles](../protocol/spec.md#identity-profiles-new)
 
 Every time that an identity is updated, for example when a credential is issued using SMT Proof or revoked, it needs to perform a [State Transition](../getting-started/state-transition/on-chain-state-transition.md). This process consists of generating a zk-proof or a digitally signed message that proves that the identity is authorized to perform the state transition.
-Then State contract verifies the proof on-chain via its [transitState](https://github.com/iden3/contracts/blob/master/contracts/state/StateV2.sol) (for zk-proofs) or [transitStateGeneric](https://github.com/iden3/contracts/blob/master/contracts/state/StateV2.sol) (generic as name suggests) function.
+Then State contract verifies the proof on-chain via its [transitState](https://github.com/iden3/contracts/blob/master/contracts/state/State.sol) (for zk-proofs) or [transitStateGeneric](https://github.com/iden3/contracts/blob/master/contracts/state/State.sol) (generic as name suggests) function.
 
-Note that the actual zk-proof verification is performed by calling the `verifyProof` function inside the [verifier.sol](https://github.com/iden3/contracts/blob/master/contracts/lib/verifier.sol) from the [`transitState`](https://github.com/iden3/contracts/blob/master/contracts/state/StateV2.sol) function inside the State Contract.
+Note that the actual zk-proof verification is performed by calling the `verifyProof` function inside the [verifier.sol](https://github.com/iden3/contracts/blob/master/contracts/lib/verifier.sol) from the [`transitState`](https://github.com/iden3/contracts/blob/master/contracts/state/State.sol) function inside the State Contract.
 
 Whenever an identity is updated, the State contract updates the corresponding leaf of the GIST Tree. This process is managed by the [SMTLib](https://github.com/iden3/contracts/blob/master/contracts/lib/SmtLib.sol) which is a Sparse Merkle Tree implementation that manages the GIST Tree and keeps track of its history.
 
-The `verifier.sol` contract is automatically generated using circom and can be used as a standalone contract to verify state transition zk-proof. `StateV2` implements further logic once the proof is verified (such as updating the GIST State).
+The `verifier.sol` contract is automatically generated using circom and can be used as a standalone contract to verify state transition zk-proof. `State` implements further logic once the proof is verified (such as updating the GIST State).
 
 ### State contract addresses
 

mkdocs/docs/getting-started/identity/identifier.md

@@ -36,7 +36,7 @@ Here is what the output would look like:
 ID: 11AbuG9EKnWVXK1tooT2NyStQod2EnLhfccSajkwJA
 ```
 
-Hereafter, this identity is represented as a mapping: `ID => IdState`. This gets published, together with all other identities, inside the `identities` mapping, which is part of the `State` [contract](../../contracts/state.md). While the ID remains constant, the Identity State will get updated as soon as the identity adds or revokes claims in its trees. 
+The identity gets published, together with all other identities, inside the struct `StateLib.Data internal _stateData` state variable, which is part of the `State` [contract](../../contracts/state.md). While the ID remains constant, the Identity State will get updated as soon as the identity adds or revokes claims in its trees. 
 
 > No Personal Identifiable Information (PPI) is stored on-chain. From the IdState is impossible to retrieve any information (represented as claim) stored inside the Identity Claims Tree
 

mkdocs/docs/getting-started/identity/identity-types.md

@@ -37,13 +37,9 @@ This type of identity was introduced to overcome some of the limitations of regu
 accounts to authenticate, prove statements and control identity (perform state transitions). That eliminates strict
 requirement to have Baby JubJub keys.
 
-Genesis Identifier and Genesis State are directly derived from the Ethereum address:
+Genesis state is always zero for Ethereum-controlled Identity.
 
-```
-genesisState = zeroPadding + ethAddress
-```
-
-So id generation is done in the following way:
+Genesis Identifier is directly derived from the Ethereum address in the following way:
 
 ```
 genesisId = idType + zeroPadding + ethAddress + checksum
@@ -63,12 +59,17 @@ idType: 0212 // DID method: PolygonID; Network: Polygon Mumbai
 +
 ethAddress: 0x0dcd1bf9a1b36ce34237eeafef220932846bcd82
 +
-checksum: 450a // checksum of idType + zeroPadding + ethAddress
+// uint16 sum of bytes of the byte string: idType + zeroPadding + ethAddress.
+// Note that the bytes of the uint16 are in reversed order, e.g. if sum is 0x0a45 then checksum is 0x450a
+checksum: 450a
 ===
-id: 0212000000000000000dcd1bf9a1b36ce34237eeafef220932846bcd82450a (bytes)
-id: 2qCU58EJgrELSJT6EzT27Rw9DhvwamAdbMLpePztYq (base58)
+id: 0A4582CD6B84320922EFAFEE3742E36CB3A1F91BCD0D000000000000001202 (bytes, reversed order)
+id: A5tDcNxacVgBQ4yHRvqv1FMR7cqNG74xGDhBWMidaq (base58)
 ```
 
+Note, that smart contracts use little-endian byte order, so the resulting identifier is reversed.
+
+
 ### DID representation
 
 Canonical form is the same as for Regular Identity:
@@ -119,10 +120,11 @@ The last two limitations can be overcome by adding BJJ keys to Claims Tree and p
 | Keys                               | BJJ keys                    | Ethereum Account (SC or EOA) | Ethereum Account (SC or EOA) + BJJ keys                    |
 | Authentication Method (off-chain)  | JWZ with ZKP using BJJ keys | JWS with Ethereum Signature  | JWS with Ethereum Signature or JWZ with ZKP using BJJ keys |
 | Authentication Method (on-chain)   | ZKP using BJJ keys          | Ethereum Account             | Ethereum Account or ZKP using BJJ keys                     |
-| State Transition Method            | ZKP using BJJ keys          | Ethereum Account             | Ethereum Account or ZKP using BJJ keys                     |
+| State Transition Method            | ZKP using BJJ keys          | Ethereum Account             | \* Ethereum Account or ZKP using BJJ keys                  |
 | Key Rotation Support               | Only BJJ keys               | Can add BJJ keys             | Only BJJ keys                                              |
 | Profiles Support                   | Yes                         | No                           | Yes                                                        |
 | Credential Issuance with MTP proof | Yes                         | Yes                          | Yes                                                        |
 | Credential Issuance with Sig proof | Yes                         | No                           | Yes                                                        |
 | Credential Revocation Support      | Yes                         | Yes                          | Yes                                                        |
 
+\* Take into account the data consistency warnings described in relevant [OnChain Identity](onchain-identity.md#state-data-consistency-warning) section. 

mkdocs/docs/getting-started/identity/onchain-identity.md

@@ -10,7 +10,7 @@ The OnChain Issuer is a special case of OnChain Identity, which is used to issue
 
 ## Libraries and Contracts
 
-* [OnChainIdentity.sol](https://github.com/iden3/contracts/blob/master/contracts/lib/OnChainIdentity.sol) - library that can create identity, manage trees, issue/revoke credentials and perform state transitions.
+* [IdentityLib.sol](https://github.com/iden3/contracts/blob/master/contracts/lib/IdentityLib.sol) - library that can create identity, manage trees, issue/revoke credentials and perform state transitions.
 * [GenesisUtils.sol](https://github.com/iden3/contracts/blob/master/contracts/lib/GenesisUtils.sol) - library that can generate id from Ethereum address or identity state and verify it.
 * [IdentityBase.sol](https://github.com/iden3/contracts/blob/master/contracts/lib/IdentityBase.sol) - base contracts to build OnChain Identity / Issuer Contracts with required public interfaces implemented.
 
@@ -22,3 +22,14 @@ The OnChain Issuer is a special case of OnChain Identity, which is used to issue
 * Private and portable web3 reputation: think of proving balance, possession of NFTs or trade volumes without disclosing your address.
 * Self-Issuance: user can go to the smart contract and issue herself a credential, that is valid and verifiable just like credentials issued by regular (off-chain) issuers.
 * ZK-Self-Issuance: it's also possible to issue credentials with private web2 data. A user can create credentials on its own device and prove that it's created correctly and follows the rules of a Smart Contract and a specific ZK Circuit. For example, a user gets digitally signed data from its own biometric document, generates a verifiable credential out of it and proves that the resulting VC corresponds to the data, and data itself is properly signed with valid government keys. Then only the hash of the credential together with zero-knowledge proof is sent on-chain to be verified and added to OnChain Identity's Claims Tree. In this way, private data never leaves the user's device and it gets valid credential.
+
+## Onchain Identity State Transition
+
+OnChain Identity State Transition is performed by calling `transitState` function of the `IdentityLib` library. The function calculates new state from the claims, revocations and roots tree roots.
+It also verifies whether roots were changed since the last state transition as a result of possible claims/revocations added to the relevant trees.
+
+As the last step, it calls `transitStateGeneric` function of the `State` contract, which is designed to be generic and in the future will be used to perform state transitions of other types of identities and/or other transition logic.
+
+#### State data consistency warning
+
+Please be aware that both the `State` contract and `IdentityLib` do not impose any restrictions on users who wish to perform a state transition using `IdentityLib.transitState()` and then subsequently perform another state transition using the `State.transitState()` contract with BJJ keys authentication. This sequence of actions has the potential to create inconsistent state data between the `State` and On-chain Identity smart contracts. It is the responsibility of the on-chain identity owner to take steps to prevent such situations from occurring.

mkdocs/docs/getting-started/state-transition/on-chain-state-transition.md

@@ -1,6 +1,6 @@
 # Verify the Proof On-Chain
 
-In order to complete the State Transition process it is necessary to verify the proof inside the `StateV2.sol` contract.
+In order to complete the State Transition process it is necessary to verify the proof inside the `State.sol` contract.
 
 The `transitState` public function of the contract takes the proof generated in the previous section and verifies it on-chain. On verification, the `identities` mapping associated with the `ID` that is executing the transition gets updated.
 
@@ -17,12 +17,12 @@ networks: {
 }
 ```
 
-2.**Add [StateV2.sol](https://github.com/iden3/contracts/blob/master/contracts/state/StateV2.sol#L148) contract and its dependencies ([Poseidon.sol](https://github.com/iden3/contracts/blob/master/contracts/lib/Poseidon.sol) and [Smt.sol](https://github.com/iden3/contracts/blob/master/contracts/lib/Smt.sol)) inside the contracts folder**
+2.**Add [State.sol](https://github.com/iden3/contracts/blob/master/contracts/state/State.sol#L148) contract and its dependencies ([Poseidon.sol](https://github.com/iden3/contracts/blob/master/contracts/lib/Poseidon.sol) and [Smt.sol](https://github.com/iden3/contracts/blob/master/contracts/lib/Smt.sol)) inside the contracts folder**
 
 3.**Import the state contract from the existing Mumbai testnet address**
 
 ```js
-const contract = await hre.ethers.getContractAt("StateV2", "0xEA9aF2088B4a9770fC32A12fD42E61BDD317E655");
+const contract = await hre.ethers.getContractAt("State", "0xEA9aF2088B4a9770fC32A12fD42E61BDD317E655");
 ```
 
 4.**Add inputs from the proof generated in the previous section**

mkdocs/docs/getting-started/state-transition/state-transition.md

@@ -10,12 +10,12 @@ This proof can be:
 
 ## ZK State Transition Verifier
 
-State Contract has `transitState` [smart contract function](https://github.com/iden3/contracts/blob/master/contracts/state/StateV2.sol), which verifies proof of `stateTransition` [circuit](../../protocol/main-circuits.md#statetransition), which represents a set of rules that identity holder needs to follow to complete the state transition such as:
+State Contract has `transitState` [smart contract function](https://github.com/iden3/contracts/blob/master/contracts/state/State.sol), which verifies proof of `stateTransition` [circuit](../../protocol/main-circuits.md#statetransition), which represents a set of rules that identity holder needs to follow to complete the state transition such as:
 
 - The prover is the owner of the identity (checked using a digital signature by the private key corresponding the `authClaim`)
 - The `authClaim` of the prover hasn't been revoked.
 
-The identity state gets updated by calling the `transitState` [smart contract function](https://github.com/iden3/contracts/blob/master/contracts/state/StateV2.sol#L148). To call this function, it is necessary to pass in the proof generated previously.
+The identity state gets updated by calling the `transitState` [smart contract function](https://github.com/iden3/contracts/blob/master/contracts/state/State.sol#L148). To call this function, it is necessary to pass in the proof generated previously.
 
 ## Ethereum State Transition Verifier
 

mkdocs/docs/protocol/spec.md

@@ -300,7 +300,7 @@ GIST, namely Global Identities State Tree, is a [Sparse Merkle Tree](../getting-
 
 The choice of using the hash of the Genesis ID as key of the leaf (instead of the Genesis ID itself) is to avoid that all the leaf accumulates in the same branch of the tree, since the Genesis ID has a fixed prefix. This would make the tree very unbalanced and inefficient. Instead, by using the hash of the Genesis ID, we randomize the position of the leaf in the tree, making it more balanced.
 
-The GIST is stored inside the [State Contract](../contracts/state.md). Every time a user executes a [State Transition function](../getting-started/state-transition/state-transition.md), the new state of an identity is [added to the GIST stored on-chain](https://github.com/iden3/contracts/blob/master/contracts/state/StateV2.sol#L190)
+The GIST is stored inside the [State Contract](../contracts/state.md). Every time a user executes a [State Transition function](../getting-started/state-transition/state-transition.md), the new state of an identity is [added to the GIST stored on-chain](https://github.com/iden3/contracts/blob/master/contracts/state/State.sol#L190)
 
 ```solidity
 gistTree.add(H(genesisID), state)
@@ -1296,4 +1296,4 @@ sequenceDiagram
 
 [//]: # ()
 [//]: # (![](../../imgs/treesAndProofs.png))
--->
+-->