From b374f93baf90f554fcbc81b839f5e69cc06f6f9f Mon Sep 17 00:00:00 2001
From: Alain Nicolas <alain.nicolas@consensys.net>
Date: Mon, 16 Oct 2023 15:40:42 +0200
Subject: [PATCH] chore: Better README

---
 README.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 65 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index d30f6cb7..38f6cc26 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,59 @@
-## Verax Attestation Registry
+<h1 align="center">
+  <br>
+  <a href="https://verax.gitbook.io/verax/"><img src="https://raw.githubusercontent.com/Consensys/linea-attestation-registry/dev/doc/verax-logo-circle.png" alt="Verax"></a>
+  <br>
+  Verax Attestation Registry
+  <br>
+</h1>
 
-**Verax, previously known as "Linea Attestation Registry", is a set of contracts that allows anyone to read and write
-attestations of any type and any subject.**
+<h4 align="center"><a href="https://verax.gitbook.io/verax/">Verax</a> is a shared registry for storing attestations of
+public interest on EVM
+chains, designed to enhance data discoverability and consumption for dApps across
+the network.</h4>
 
-<p style="text-align: center;">
-  <img src="https://github.com/Consensys/linea-attestation-registry/blob/dev/doc/verax-logo-circle.png" alt="Verax Logo"/>
+<p align="center">
+  <a href="#links">Links</a> •
+  <a href="#repository-organisation">Repository Organisation</a> •
+  <a href="#contributing">Contributing</a> •
+  <a href="#contracts-addresses">Contracts Addresses</a> •
+  <a href="#linking-attestations">Linking Attestations</a> •
+  <a href="#license">License</a>
 </p>
 
-## Contribution
+## Links
+
+📚 [Official documentation](https://verax.gitbook.io/verax/)  
+🔍
+[Testnet GraphQL API](https://graph-query.goerli.linea.build/subgraphs/name/Consensys/linea-attestation-registry/graphql)  
+🔍 [Mainnet GraphQL API](https://graph-query.linea.build/subgraphs/name/Consensys/linea-attestation-registry/graphql)  
+🧱 Verax SDK - _Coming soon_  
+🌍 Verax Explorer - _Coming soon_
+
+## Repository Organisation
+
+```
+.
+├── contracts   # All smart contracts needed to run Verax
+├── explorer    # Explorer frontend to discover the main objects (Coming soon)
+├── sdk         # The verax-sdk to easily interact with the contracts and the subgraph
+├── subgraph    # The subgraph indexing Verax data
+```
+
+## Contributing
 
 Verax Attestation Registry is a community-led initiative, with developers from various companies and different
 backgrounds. While we are more than happy to get help from multiple sources, we need to rely on strong Ways of Working.
 
 Don't hesitate to check our [Contribution Guide](./CONTRIBUTING.md) before pushing your first code to the repo!
 
-## Contracts addresses
+## Contracts Addresses
+
+The main contracts (i.e. the "registries") and the helpers contracts are deployed on Linea Goerli (Testnet) and Linea
+Mainnet.  
+Here are the addresses on the 2 networks:
 
-### Linea Testnet
+<details>
+  <summary>Linea Testnet</summary>
 
 - Router =
   [0x736c78b2f2cBf4F921E8551b2acB6A5Edc9177D5](https://goerli.lineascan.build/address/0x736c78b2f2cBf4F921E8551b2acB6A5Edc9177D5)
@@ -31,7 +68,10 @@ Don't hesitate to check our [Contribution Guide](./CONTRIBUTING.md) before pushi
 - AttestationReader =
   [0x65c8294C7aF0f0bDDe51eF92AF850613bb629fc6](https://goerli.lineascan.build/address/0x65c8294C7aF0f0bDDe51eF92AF850613bb629fc6)
 
-### Linea Mainnet
+</details>
+
+<details>
+  <summary>Linea Mainnet</summary>
 
 - Router =
   [0x4d3a380A03f3a18A5dC44b01119839D8674a552E](https://lineascan.build/address/0x4d3a380A03f3a18A5dC44b01119839D8674a552E)
@@ -46,7 +86,20 @@ Don't hesitate to check our [Contribution Guide](./CONTRIBUTING.md) before pushi
 - AttestationReader =
   [0x40871e247CF6b8fd8794c9c56bB5c2b8a4FA3B6c](https://lineascan.build/address/0x40871e247CF6b8fd8794c9c56bB5c2b8a4FA3B6c)
 
-## Relationship Schemas IDs (testnet & mainnet)
+</details>
+
+## Linking Attestations
+
+Verax Attestation Registry allows creating links ("relationships") between attestations.  
+🔗 Go to the
+[official documentation](https://verax.gitbook.io/verax/developer-guides/for-attestation-issuers/link-attestations) for
+more details
+
+Verax offers 2 Schemas to cover most use cases, both on testnet and mainnet:
+
+- The **Relationship** Schema, with ID `0x41b8c81288eebbf173b2f54b9fb2f1d37f2caca51ef39e8f99299b53c2599a3a`
+- The **Named Graph Relationship** Schema with ID `0x8f83a0ef7871f63455a506f6bca0db98a88721764ae6dbde2afddd8e12e442b8`
+
+## License
 
-- **Relationship** Schema ID = `0x89bd76e17fd84df8e1e448fa1b46dd8d97f7e8e806552b003f8386a5aebcb9f0`
-- **namedGraphRelationship** Schema ID = `0x5003a7832fa2734780a5bf6a1f3940b84c0c66a398e62dd4e7f183fdbc7da6ee`
+[MIT](./LICENSE)