Update identity documentation

packages/docs/SUMMARY.md

@@ -36,6 +36,7 @@
     - [Encrypted Payment Comments](celo-codebase/protocol/transactions/tx-comment-encyption.md)
     - [Full Node Incentives](celo-codebase/protocol/transactions/full-node-incentives.md)
   - [Lightweight Identity](celo-codebase/protocol/identity/README.md)
+    - [Metadata](celo-codebase/protocol/identity/metadata.md)
     - [Randomness](celo-codebase/protocol/identity/randomness.md)
   - [Stability Mechanism](celo-codebase/protocol/stability/README.md)
     - [Stability Algorithm \(CP-DOTO\)](celo-codebase/protocol/stability/doto.md)

packages/docs/celo-codebase/protocol/identity/README.md

@@ -6,9 +6,9 @@ Celo’s unique purpose is to make financial tools accessible to anyone with a m
 
 ### **Adding their phone number to the mapping**
 
-To allow Bob to find an address mapped to her phone number, Alice can request attestations to their phone number \(technically the hash of their phone number\) from the `Attestations` contract by transferring the attestation request fee to it. The fee per attestation request is set on the contract with Governance. The `Attestations` contract will use the `Random` contract to do a random selection over the current validator set in the `Validators` contract who will become responsible for these attestation requests. In the current version of the `Attestations` contract, Alice will look up the encryption key of those validators \(that they set on the `Attestations` contract itself\), and reveal their phone number to the validator only.
+To allow Bob to find an address mapped to her phone number, Alice can request attestations to their phone number \(technically the hash of their phone number\) from the `Attestations` contract by transferring the attestation request fee to it. The fee per attestation request is set on the contract with [Governance](../governance.html). After a brief waiting time of currently `4` blocks, the `Attestations` contract will use the `Random` contract to do a random selection over the current validator set in the `Validators` contract who will become responsible for these attestation requests.
 
-As part of the expectation to validators, they observe those reveals and then produce a signed secret message that acts as an attestation by that validator that Alice owns the phone number. The validator sends that message to the revealed phone number via SMS. Read more under text message sending service.
+As part of the expectation to validators, they run the attestation service whose endpoint they register in their [Metadata](./metadata.html). Alice can identify the validators responsible for her attestation from the smart contract, determine the validators' attestation service URLs from their [Metadata](./metadata.html) and request attestations from them. In turn, the attestation service produces a signed secret message that acts as an attestation by that validator that Alice owns the phone number. The validator sends that message via SMS. Read more under [attestation service](#attestation-service).
 
 When Alice receives the text message, she can take that signed message to the `Attestations` contract, which can verify that the attestation came from the validator indeed. Upon a successful attestation, the validator can redeem for the attestation request fee to pay them for the cost of sending the SMS. In the end, we have recorded an attestation by the validator to a mapping of Alice’s phone number to her account address.
 
@@ -24,8 +24,8 @@ There are additional measures we can take to further secure the integrity of the
 
 One downside to this identity protocol is that knowledge of a phone number can let anyone quickly determine the balance of the associated wallet, which of course may be unacceptable for many use cases. For these circumstances, the contract allows users to use the `Attestations` contract in privacy mode. In this mode, the user does not map their phone number to their wallet address, but to an account that is not meant to be the recipient of transfers. Through a registered encryption key on the user’s account on the contract, schemes can be derived to allow users to selectively reveal their true wallet addresses to authorized participants. Implementing such a scheme is future work.
 
-### **Text messaging service**
+### **Attestation service**
 
-We have a service that we built that we currently call the `Verification Pool` that allows validators to make an HTTP POST request to and that service then sends the SMS to Alice via Twilio. We expect that in the future, validators run their own version of a service like the `Verification Pool`. For Alfajores, Celo Labs will be hosting a single instance of the `Verification Pool` that anyone can use.
+The attestation service is a simple Node.js service that validators run to send signed messages for attestations. It can be configured with SMS providers, as different providers have different characteristics like reliability, trustworthiness and performance in different regions. The attestation service currently supports [Twilio](https://www.twilio.com) and [Nexmo](https://nexmo.com). We hope to widen the number of supported providers, especially for service in relevant regions.
 
-We have been experimenting with an extension to the `Verification Pool` that we would like community feedback on. Instead of sending the SMS via Twilio, users of a `Rewards Mobile App` could register themselves with the `Verification Pool` and be made responsible for sending those text messages. It would allow users with cheap or leftover SMS capacity from their cell phone plan to effectively acquire a share of the attestation request fees. It would represent a unique on-ramp for users who do not have access to classic on-ramps like exchanges. However, we are currently unsure of the game-theoretical implications of “pooling” the attestation requests to non-validators and thus explicitly labeling it as an experiment.
+We have been experimenting with a SMS provider that we would like community feedback on. Instead of sending the SMS via conventinal providers like Twilio, users of a `Rewards Mobile App` could register themselves with a `Verification Pool` and be made responsible for sending those text messages. It would allow users with cheap or leftover SMS capacity from their cell phone plan to effectively acquire a share of the attestation request fees. It would represent a unique on-ramp for users who do not have access to classic on-ramps like exchanges. Validators could configure their attestation service to use such a SMS provider which could in theory provide better inclusion and performance.

packages/docs/celo-codebase/protocol/identity/metadata.md

@@ -0,0 +1,55 @@
+# Metadata
+
+Oftentimes, it is necessary to connect on-chain with off-chain identities.
+
+Use cases include:
+
+- Tools want to present public metadata supplied by a validator or validator group as part of a list of candidate groups, or a list of current elected validators.
+- Governance Explorer UIs may want to present public metadata about the creators of governance proposals
+- The Celo Foundation receives notice of a security vulnerability and wants to contact elected validators to facilitate them to make a decision on applying a patch.
+- A DApp makes a request to the Celo Wallet for account information or to sign a transaction. The Celo Wallet should provide information about the DApp to allow the user to make a decision whether to sign the transaction or not.
+
+Furthermore, we want to include user chosen information such as names or profile pictures that would be expensive to store on-chain. For this purpose, we have a mechanism we call `Metadata` to allow accounts to make both verifiable as well as non-verifiable claims (highly inspired by [Keybase](https://keybase.io)). Check out the [CIP3](https://github.com/celo-org/CIPs/pull/4)
+
+On the `Accounts` smart contract, any account can register a URL under which their metadata file is available under. In that metadata file is the list of claims, signed by the account. We currently support the following claims:
+
+**Name Claim**
+An account can claim a human-readable name. This claim is not verifiable.
+
+**Attestation Service URL Claim**
+For the [lightweight identity layer](../), validators can make a claim under which their attestation service is reachable to provide attestations. This claim is not verifiable.
+
+**Keybase User Claim**
+Accounts can make claims on Keybase usernames. This claim is verifiable by signing a message with the account and hosting it on the publicly accessible path of the Keybase file system.
+
+Future Claims we hope to support soon:
+
+**Twitter User Claim**
+Accounts can make claims on Keybase usernames. This claim is verifiable by siging a message with the account and posting it as a tweet. Any client can verify the claim with a reference to the tweet in the claim.
+
+**Domain Claim**
+Accounts can make claims on domain names. This claim is verifiable by signing a message with the account and embedding it in a TXT record.
+
+### Handling Metadata
+
+You can interact with metadata files easily through the CLI. Most commands require a node being available under http://localhost:8545 to make view calls, and to modify metadata files, you'll need the relevant account to be unlocked to sign the files.
+
+You can create an empty metadata file with:
+
+`$celocli account:create-metadata ./metadata.json --from $ACCOUNT_ADDRESS`
+
+You can add claims with various commands:
+
+`$celocli account:claim-attestation-service-url ./metadata.json --from $ACCOUNT_ADDRESS --url $ATTESTATION_SERVICE_URL`
+
+You can display the claims in your file and their status with:
+
+`$celocli account:show-metadata ./metadata.json`
+
+Once you are satisfied with your claims, you can upload your file to your trusted hoster (something like [https://gist.github.com](https://gist.github.com) works) and then register it with the `Accounts` smart contract by running:
+
+`$celocli account:register-metadata --url $METADATA_URL --from $ACCOUNT_ADDRESS`
+
+Then, anyone can lookup your claims and verify them by running:
+
+`$celocli account:get-metadata $ACCOUNT_ADDRESS`