feat: introduce comprehensive GitBook documentation structure with build instructions, feature guides, a validation workflow, and updated README links.

siyovush-hamidov · siyovush-hamidov · commit 0b54ee7b9fa1 · 2026-02-27T11:26:36.000+01:00
diff --git a/.github/workflows/docs-validation.yml b/.github/workflows/docs-validation.yml
@@ -0,0 +1,24 @@
+name: Docs Validation
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'docs/**'
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - 'docs/**'
+
+jobs:
+  lint-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Lint markdown files
+        uses: davidanson/markdownlint-cli2-action@v15
+        with:
+          globs: |
+            docs/**/*.md
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -0,0 +1,6 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+  "MD041": false
+}
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # on-chain-ssi
 
+[![GitBook Documentation](https://img.shields.io/badge/GitBook-Documentation-blue?logo=gitbook)](docs/getting-started.md)
+
 ## About
 
 On-Chain Self-Sovereign Identity (SSI) architecture migrating CRSet from Ethereum Blobs to Tezos Etherlink. This project enables organizations to issue and verify decentralized digital identities anchored on blockchain, providing cryptographic proof of identity without relying on centralized authorities.
@@ -125,11 +127,16 @@ Open http://localhost:5173/ in your browser.
 
 ## Documentation
 
+The comprehensive project features and setup information are part of the GitBook documentation. You can find the source in the [`docs/`](docs/) directory.
+
+- **[📖 GitBook Documentation](docs/getting-started.md)** - Main entry point
 - **[BUILD.md](BUILD.md)** - Comprehensive build instructions, testing, troubleshooting, and deployment guides
 - **[CI_CD.md](CI_CD.md)** - CI/CD pipeline documentation with workflow details and troubleshooting
 - **[Smart Contracts](packages/trust-anchor-did-ethr/README.md)** - Detailed smart contract documentation
 - **[Demo Application](packages/demo-app-frontend/README.md)** - Frontend application guide
 
+To contribute to the documentation, simply modify the Markdown files in the `docs/` directory and create a Pull Request. GitBook will automatically synchronize the changes via its native GitHub App.
+
 ## License
 
 This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -0,0 +1,10 @@
+# Table of contents
+
+* [Getting Started](getting-started.md)
+* [Build & Setup Instructions](build-instructions.md)
+
+## Features
+
+* [Registry Contracts](features/registry-contracts.md)
+* [Issuer Service](features/issuer-service.md)
+* [Verifier Service](features/verifier-service.md)
diff --git a/docs/build-instructions.md b/docs/build-instructions.md
@@ -0,0 +1,132 @@
+# Build & Setup Instructions
+
+## Prerequisites
+
+Before starting, ensure you have the following installed on your system:
+
+- **Node.js**: ≥ 22.12.0 (Required for Hardhat 3 and Vite 7)
+- **NPM**: ≥ 10.0.0
+- **MetaMask**: Browser extension for managing Ethereum accounts
+
+> [!WARNING]
+> Do not use Node.js 20.x, as it will cause Hardhat runtime errors. Use a version manager like `nvm` to ensure you are on `22.12.0` or higher:
+>
+> ```bash
+> nvm install 22
+> nvm use 22
+> ```
+
+## 1. Installation
+
+Start by cloning the repository and installing both the root and package-specific dependencies.
+
+```bash
+# Install root dependencies (including Husky pre-commit hooks)
+npm install
+
+# Install smart contract dependencies
+cd packages/trust-anchor-did-ethr
+npm install
+
+# Install frontend dependencies
+cd ../demo-app-frontend
+npm install
+
+# Return to root directory
+cd ../..
+```
+
+## 2. Compile and Run the Blockchain (Hardhat)
+
+You'll need a local Ethereum network to deploy the registry contracts. Ensure you run this in a **dedicated terminal** and leave it open.
+
+```bash
+cd packages/trust-anchor-did-ethr
+
+# Start Hardhat local node
+npx hardhat node
+```
+
+Once running, Hardhat will output a list of test accounts and private keys. Keep this window open.
+
+## 3. Deploy Smart Contracts
+
+Open a **new terminal** and deploy the initial Trust Anchor and Registry contracts to the local network:
+
+```bash
+cd packages/trust-anchor-did-ethr
+
+# Deploy the modules using Hardhat Ignition
+npx hardhat ignition deploy ignition/modules/CompanyCRSet.ts --network localhost
+```
+
+**Important**: The deployment process will output the contract addresses. **Copy these addresses**, as you will need them for the frontend configuration.
+
+Example output:
+
+```text
+CompanyCRSetModule#EthereumDIDRegistry - 0xabcd...1234
+CompanyCRSetModule#DIDMultisigController - 0xef01...5678
+CompanyCRSetModule#CompanyCRSetRegistry - 0x9abc...def0
+```
+
+## 4. Frontend Configuration
+
+Navigate to the frontend package and configure the environment variables:
+
+```bash
+cd packages/demo-app-frontend
+
+# Copy the example environment file
+cp .env.example .env
+```
+
+Open the `.env` file and replace the placeholder addresses with the addresses you received from the contract deployment step:
+
+| Variable | Description | Value from Deployment |
+| :--- | :--- | :--- |
+| `VITE_TRUST_ANCHOR_ADDRESS` | Address of the Trust Anchor multisig | `CompanyCRSetModule#DIDMultisigController` |
+| `VITE_REGISTRY_ADDRESS` | Address of the baseline DID registry | `CompanyCRSetModule#EthereumDIDRegistry` |
+| `VITE_CRSET_REGISTRY_ADDRESS` | Address of the revocation registry | `CompanyCRSetModule#CompanyCRSetRegistry` |
+| `VITE_PINATA_JWT` | JWT for Pinata IPFS access (Optional for local testing) | *Your Pinata Token* |
+| `VITE_HARDHAT_RPC_URL` | Local RPC endpoint | `http://127.0.0.1:8545` |
+
+## 5. Configure MetaMask
+
+To interact with the local development environment:
+
+1. Add a **Custom Network** to MetaMask:
+   - **Network Name**: Hardhat Local
+   - **RPC URL**: `http://127.0.0.1:8545`
+   - **Chain ID**: `31337`
+   - **Currency Symbol**: `ETH`
+2. **Import Accounts**: Import the first few (1-5) private keys provided by the Hardhat node terminal into MetaMask to act as the Trust Anchor admins.
+
+## 6. Run the Application
+
+Start the local Vite development server for the frontend application:
+
+```bash
+cd packages/demo-app-frontend
+npm run dev
+```
+
+The application will be accessible at [http://localhost:5173/](http://localhost:5173/).
+
+## Additional Commands
+
+### Testing Contracts
+
+```bash
+cd packages/trust-anchor-did-ethr
+npx hardhat test
+```
+
+### Production Build (Frontend)
+
+```bash
+cd packages/demo-app-frontend
+npm run build
+```
+
+This generates the optimized `dist/` artifacts required if you intend to serve the application via Docker or static hosting.
diff --git a/docs/features/issuer-service.md b/docs/features/issuer-service.md
@@ -0,0 +1,50 @@
+# Issuer Service
+
+> [!NOTE]
+> The `issuer-service` is currently a placeholder package within the `on-chain-ssi` monorepo. The core verifiable credential issuance logic is expected to be implemented here in the future.
+
+## Overview and Purpose
+
+The Issuer Service is responsible for generating and signing Verifiable Credentials (VCs) for users or organizations within the On-Chain SSI ecosystem. It acts as the authority that attests to specific claims about a subject.
+
+While the dedicated backend service is pending implementation, some issuance flows (such as registering companies and adding test credentials) are currently demonstrated via the `demo-app-frontend`, which interacts directly with the smart contracts using the test accounts.
+
+## Technical Details
+
+Currently, the `packages/issuer-service/` directory contains placeholder files. Once implemented, this service is expected to:
+
+- **DID Method**: Utilize `did:ethr` for resolving and anchoring identities.
+- **Credential Format**: Issue W3C standard Verifiable Credentials (typically JWT or JSON-LD format).
+- **Architecture**: Likely a Node.js/TypeScript backend service or an Express/NestJS API that holds the private key of the issuer.
+
+## Usage Examples
+
+> Note: These are illustrative examples based on the planned architecture. Actual implementation may vary once the service is fully developed in the repository.
+
+### Planned API Endpoint (Illustrative)
+
+```http
+POST /api/v1/issue-credential
+Content-Type: application/json
+
+{
+  "subjectDid": "did:ethr:sepolia:0x1234567890abcdef1234567890abcdef12345678",
+  "claims": {
+    "organizationName": "Acme Corp",
+    "role": "Verified Partner"
+  }
+}
+```
+
+### Current Frontend Issuance (Workaround)
+
+In the current demo, the Trust Anchor (using a Hardhat test account) directly registers a company on-chain, effectively "issuing" them the right to act within the ecosystem:
+
+```javascript
+// Example from frontend hooks (useTrustAnchor.ts context)
+const addCompanyAdmin = async (companyDID, adminAddress) => {
+  // Trust Anchor multisig executes transaction to authorize a company admin
+  const tx = await registryContract.addCompanyAdmin(companyDID, adminAddress);
+  await tx.wait();
+};
+```
diff --git a/docs/features/registry-contracts.md b/docs/features/registry-contracts.md
@@ -0,0 +1,85 @@
+# Registry Contracts
+
+The `trust-anchor-did-ethr` package forms the on-chain foundation of the SSI ecosystem. It provides the smart contracts necessary for decentralized identity management, governance, and revocation.
+
+## Overview and Purpose
+
+The smart contracts are responsible for defining organizational identities, establishing a governing authority (Trust Anchor), and maintaining pointers to off-chain revocation data. There are three primary components:
+
+1. **`EthereumDIDRegistry`**: The standard registry mapping Ethereum addresses to their Decentralized Identifiers (DIDs).
+2. **`DIDMultisigController`**: A multisig governance contract that acts as the highest authority (Trust Anchor).
+3. **`CompanyCRSetRegistry`**: A registry mapping company DIDs to their Credential Revocation Set (CRSet) IPFS CIDs.
+
+## Technical Details
+
+### 1. EthereumDIDRegistry
+
+- **Methodology**: Implements the [`did:ethr`](https://github.com/decentralized-identity/ethr-did-resolver) method.
+- **Features**: Allows changing identity owners, adding/revoking delegates, and setting attributes via direct calls or meta-transactions (signed payloads).
+
+### 2. DIDMultisigController
+
+- **Architecture**: An M-of-N multisig wallet designed to control identities.
+- **Layers**:
+  - **Speed Layer (Single Admin)**: A single owner can execute calls to external contracts (`execCall`), allowing fast administrative operations on sub-identities.
+  - **Security Layer (Consensus)**: Requires quorum (M-of-N) or unanimous approval for critical system changes (e.g., changing the Trust Anchor's own identity, adding/removing multisig owners, or proposing proxy upgrades).
+  
+### 3. CompanyCRSetRegistry
+
+- **Architecture**: Maps a company's DID to an IPFS Content Identifier (CID). The CID points to a Bloom Filter Cascade representing revoked credentials.
+- **Governance**: Owned by the `DIDMultisigController` (Trust Anchor). Only the Trust Anchor can add or remove authorized company admins.
+- **Usage**: Authorized company admins update their own CID (`updateRevocationCID()`) without interacting directly with raw DID documents.
+
+## Usage Examples
+
+### Deploying the Contracts
+
+Deployment is handled via Hardhat Ignition (`ignition/modules/CompanyCRSet.ts`):
+
+```bash
+cd packages/trust-anchor-did-ethr
+npx hardhat ignition deploy ignition/modules/CompanyCRSet.ts --network localhost
+```
+
+### Trust Anchor Adding a Company Admin
+
+The `CompanyCRSetRegistry` relies on the Trust Anchor to whitelist company administrators:
+
+```solidity
+// Only the Trust Anchor (Multisig) can call this
+function addCompanyAdmin(address companyDID, address admin) external onlyOwner {
+    if (companyDID == address(0) || admin == address(0)) revert InvalidAddress();
+    if (companyAdmins[companyDID][admin]) revert AdminAlreadyExists();
+
+    companyAdmins[companyDID][admin] = true;
+    emit CompanyAdminAdded(companyDID, admin, block.timestamp);
+}
+```
+
+### Company Updating Revocation CID
+
+Once authorized, a company admin updates the IPFS hash for their revoked credentials:
+
+```solidity
+// Called directly by the whitelisted company admin
+function updateRevocationCID(address companyDID, string calldata newCID) external onlyCompanyAdmin(companyDID) {
+    if (bytes(newCID).length == 0) revert EmptyCID();
+
+    revocationCIDs[companyDID] = newCID;
+    emit RevocationCIDUpdated(companyDID, newCID, msg.sender, block.timestamp);
+}
+```
+
+### Creating a Multisig Proposal
+
+To execute a sensitive action on the Trust Anchor identity itself, a proposal must be created and approved:
+
+```javascript
+// Create a proposal to add a new owner to the multisig
+const txPropose = await multisigController.proposeAddOwner(newOwnerAddress);
+const receipt = await txPropose.wait();
+const proposalId = receipt.logs[0].args.id;
+
+// Other owners must approve the proposal
+const txApprove = await multisigController.connect(owner2).approve(proposalId);
+```
diff --git a/docs/features/verifier-service.md b/docs/features/verifier-service.md
@@ -0,0 +1,58 @@
+# Verifier Service
+
+> [!NOTE]
+> The `verifier-service` is currently a placeholder package within the `on-chain-ssi` monorepo. The verification logic is part of the future implementation roadmap.
+
+## Overview and Purpose
+
+The Verifier Service's role is to receive Verifiable Presentations (VPs) or Verifiable Credentials (VCs) from users (Holders) and cryptographically verify their authenticity, integrity, and validity against the on-chain registry.
+
+Currently, validation of identity statuses (like checking if an address is an authorized company admin) is performed directly by the smart contracts and the frontend application.
+
+## Technical Details
+
+The `packages/verifier-service/` directory holds placeholder files. The completed service is designed to handle:
+
+- **DID Resolution**: Resolving `did:ethr` documents from the `EthereumDIDRegistry`.
+- **Revocation Checking**: Checking the `CompanyCRSetRegistry` for a company's current Credential Revocation Set (CRSet) via IPFS/Bloom Filters to ensure credentials haven't been revoked.
+- **Signature Verification**: Verifying the issuer's cryptographic signature on the VC/VP.
+
+## Usage Examples
+
+> Note: These are illustrative examples based on the system's architecture. The verifiable logic shown here represents the planned flow.
+
+### Checking Revocation Status (Current On-Chain Flow)
+
+The verification process relies on the `CompanyCRSetRegistry` to find the latest revocation list (CRSet) for an issuer:
+
+```solidity
+// CompanyCRSetRegistry.sol
+// Verifiers call this to get the IPFS CID of the company's revocation set
+function getRevocationCID(address companyDID) external view returns (string memory) {
+    return revocationCIDs[companyDID];
+}
+```
+
+### Planned API Endpoint (Illustrative)
+
+```http
+POST /api/v1/verify
+Content-Type: application/json
+
+{
+  "verifiablePresentation": "eyJhbGciOiJFUzI1Nksi...[VP Token]..."
+}
+```
+
+### Verifying an Identity (Frontend/Smart Contract Context)
+
+To verify if an address is authorized to manage a company's identity before accepting their credentials:
+
+```javascript
+// Call to CompanyCRSetRegistry
+const isAuthorized = await crsetRegistry.isCompanyAdmin(companyDid, userAddress);
+
+if (!isAuthorized) {
+  throw new Error("This user is not an authorized administrator for the company.");
+}
+```
diff --git a/docs/getting-started.md b/docs/getting-started.md
