adding docs

.github/workflows/gh-pages.yml

@@ -0,0 +1,30 @@
+name: github pages
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: "0.4.10"
+          # mdbook-version: 'latest'
+
+      - run: cd docs; mdbook build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/book

.gitignore

@@ -2,6 +2,7 @@
 cache/
 out/
 .DS_Store
+docs/
 
 # Ignores development broadcast logs
 /broadcast

foundry.toml

@@ -13,6 +13,7 @@ number_underscore="thousands"
 
 [doc]
 title = "Rhinestone Registry"
+ignore = ["src/DataTypes.sol", "src/Common.sol", "src/external"]
 
 [invariant]
 # fail_on_revert = true

package.json

@@ -52,6 +52,7 @@
     "prepack": "pnpm install",
     "test": "forge test",
     "test:lite": "FOUNDRY_PROFILE=lite forge test",
-    "test:optimized": "pnpm run build:optimized && FOUNDRY_PROFILE=test-optimized forge test"
+    "test:optimized": "pnpm run build:optimized && FOUNDRY_PROFILE=test-optimized forge test",
+    "build:docs": "forge doc && cd ./docs && rm -rf ./src/src/DataTypes.sol; mdbook build && cd .."
   }
 }

src/DataTypes.sol

@@ -8,7 +8,6 @@ import { IExternalResolver } from "./external/IExternalResolver.sol";
 /*                     Storage Structs                        */
 /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
-// Struct that represents an attestation.
 struct AttestationRecord {
     uint48 time; // The time when the attestation was created (Unix timestamp).
     uint48 expirationTime; // The time when the attestation expires (Unix timestamp).
@@ -20,7 +19,6 @@ struct AttestationRecord {
     SchemaUID schemaUID; // The unique identifier of the schema.
 }
 
-// Struct that represents Module artefact.
 struct ModuleRecord {
     ResolverUID resolverUID; // The unique identifier of the resolver.
     address sender; // The address of the sender who deployed the contract

src/IRegistry.sol

@@ -42,6 +42,17 @@ interface IERC7484 {
     function checkN(address module, ModuleType moduleType, address[] calldata attesters, uint256 threshold) external view;
 }
 
+/**
+ * Interface definition of all features of the registry:
+ *      - Register Schemas
+ *      - Register External Resolvers
+ *      - Register Modules
+ *      - Make Attestations
+ *      - Make Revocations
+ *      - Delegate Trust to Attester(s)
+ *
+ * @author rhinestone | zeroknots.eth, Konrad Kopp (@kopy-kat)
+ */
 interface IRegistry is IERC7484 {
     /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
     /*             Smart Account - Trust Management               */
@@ -60,9 +71,9 @@ interface IRegistry is IERC7484 {
     error InsufficientAttestations();
 
     /**
-     * Allows smartaccounts - the end users of the registry - to appoint
+     * Allows Smart Accounts - the end users of the registry - to appoint
      * one or many attesters as trusted.
-     * @notice this function reverts, if address(0), or duplicates are provided in attesters[]
+     * @dev this function reverts, if address(0), or duplicates are provided in attesters[]
      *
      * @param threshold The minimum number of attestations required for a module
      *                  to be considered secure.
@@ -71,8 +82,8 @@ interface IRegistry is IERC7484 {
     function trustAttesters(uint8 threshold, address[] calldata attesters) external;
 
     /**
-     * Get trusted attester for a specific smartAccount
-     * @param smartAccount The address of the smartAccount
+     * Get trusted attester for a specific Smart Account
+     * @param smartAccount The address of the Smart Account
      */
     function findTrustedAttesters(address smartAccount) external view returns (address[] memory attesters);
 
@@ -93,8 +104,8 @@ interface IRegistry is IERC7484 {
     error InvalidModuleTypes();
 
     /**
-     * Allows msg.sender to attest to multiple modules' security status.
-     * The AttestationRequest.Data provided should match the attestation
+     * Allows `msg.sender` to attest to multiple modules' security status.
+     * The `AttestationRequest.Data` provided should match the attestation
      * schema defined by the Schema corresponding to the SchemaUID
      *
      * @dev This function will revert if the same module is attested twice by the same attester.
@@ -106,8 +117,8 @@ interface IRegistry is IERC7484 {
     function attest(SchemaUID schemaUID, AttestationRequest calldata request) external;
 
     /**
-     * Allows msg.sender to attest to multiple modules' security status.
-     * The AttestationRequest.Data provided should match the attestation
+     * Allows `msg.sender` to attest to multiple modules' security status.
+     * The `AttestationRequest.Data` provided should match the attestation
      * schema defined by the Schema corresponding to the SchemaUID
      *
      * @dev This function will revert if the same module is attested twice by the same attester.
@@ -119,8 +130,8 @@ interface IRegistry is IERC7484 {
     function attest(SchemaUID schemaUID, AttestationRequest[] calldata requests) external;
 
     /**
-     * Allows attester to attest by signing an AttestationRequest (ECDSA or ERC1271)
-     * The AttestationRequest.Data provided should match the attestation
+     * Allows attester to attest by signing an `AttestationRequest` (`ECDSA` or `ERC1271`)
+     * The `AttestationRequest.Data` provided should match the attestation
      * schema defined by the Schema corresponding to the SchemaUID
      *
      * @dev This function will revert if the same module is attested twice by the same attester.
@@ -134,8 +145,8 @@ interface IRegistry is IERC7484 {
     function attest(SchemaUID schemaUID, address attester, AttestationRequest calldata request, bytes calldata signature) external;
 
     /**
-     * Allows attester to attest by signing an AttestationRequest (ECDSA or ERC1271)
-     * The AttestationRequest.Data provided should match the attestation
+     * Allows attester to attest by signing an `AttestationRequest` (`ECDSA` or `ERC1271`)
+     * The `AttestationRequest.Data` provided should match the attestation
      * schema defined by the Schema corresponding to the SchemaUID
      *
      * @dev This function will revert if the same module is attested twice by the same attester.
@@ -169,17 +180,17 @@ interface IRegistry is IERC7484 {
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
     /**
-     * Allows msg.sender to revoke an attstation made by the same msg.sender
+     * Allows `msg.sender` to revoke an attestation made by the same `msg.sender`
      *
      * @dev this function will revert if the attestation is not found
      * @dev this function will revert if the attestation is already revoked
      *
-     * @param request  the RevocationRequest
+     * @param request single RevocationRequest
      */
     function revoke(RevocationRequest calldata request) external;
 
     /**
-     * Allows msg.sender to revoke multiple attstations made by the same msg.sender
+     * Allows msg.sender to revoke multiple attestation made by the same msg.sender
      *
      * @dev this function will revert if the attestation is not found
      * @dev this function will revert if the attestation is already revoked
@@ -189,16 +200,16 @@ interface IRegistry is IERC7484 {
     function revoke(RevocationRequest[] calldata requests) external;
 
     /**
-     * Allows attester to revoke an attestation by signing an RevocationRequest (ECDSA or ERC1271)
+     * Allows attester to revoke an attestation by signing an `RevocationRequest` (`ECDSA` or `ERC1271`)
      *
      * @param attester the signer / revoker
-     * @param request the RevocationRequest
+     * @param request single RevocationRequest
      * @param signature ECDSA or ERC1271 signature
      */
     function revoke(address attester, RevocationRequest calldata request, bytes calldata signature) external;
 
     /**
-     * Allows attester to revoke an attestation by signing an RevocationRequest (ECDSA or ERC1271)
+     * Allows attester to revoke an attestation by signing an `RevocationRequest` (`ECDSA` or `ERC1271`)
      * @dev if you want to revoke multiple attestations, but from different attesters, call this function multiple times
      *
      * @param attester the signer / revoker
@@ -219,12 +230,12 @@ interface IRegistry is IERC7484 {
     error FactoryCallFailed(address factory);
 
     /**
-     * This registry implements a CREATE2 factory, that allows module developers to register and deploy module bytecode
-     * @param salt The salt to be used in the CREATE2 factory. This adheres to Pr000xy/Create2Factory.sol salt formatting.
+     * This registry implements a `CREATE2` factory, that allows module developers to register and deploy module bytecode
+     * @param salt The salt to be used in the `CREATE2` factory. This adheres to Pr000xy/Create2Factory.sol salt formatting.
      *             The salt's first bytes20 should be the address of the sender
      *             or bytes20(0) to bypass the check (this will lose replay protection)
-     * @param resolverUID The resolverUID to be used in the CREATE2 factory
-     * @param initCode The initCode to be used in the CREATE2 factory
+     * @param resolverUID The resolverUID to be used in the `CREATE2` factory
+     * @param initCode The initCode to be used in the `CREATE2` factory
      * @param metadata The metadata to be stored on the registry.
      *            This field is optional, and might be used by the module developer to store additional
      *            information about the module or facilitate business logic with the Resolver stub
@@ -297,14 +308,14 @@ interface IRegistry is IERC7484 {
     error InvalidSchemaValidator(IExternalSchemaValidator validator);
 
     /**
-     * Register Schema and (optional) external IExternalSchemaValidator
-     * Schemas describe the structure of the data of attestations
+     * Register Schema and (optional) external `IExternalSchemaValidator`
+     * A Schema describe the structure of the data of attestations
      * every attestation made on this registry, will reference a SchemaUID to
      *  make it possible to decode attestation data in human readable form
      * overrwriting a schema is not allowed, and will revert
      * @param schema ABI schema used to encode attestations that are made with this schema
      * @param validator (optional) external schema validator that will be used to validate attestations.
-     *                  use address(0), if you dont need an external validator
+     *                  use address(0), if you don't need an external validator
      * @return uid SchemaUID of the registered schema
      */
     function registerSchema(
@@ -315,7 +326,7 @@ interface IRegistry is IERC7484 {
         returns (SchemaUID uid);
 
     /**
-     * getter function to retrieve SchemaRecord
+     * Getter function to retrieve SchemaRecord
      */
     function findSchema(SchemaUID uid) external view returns (SchemaRecord memory record);
 
@@ -336,7 +347,7 @@ interface IRegistry is IERC7484 {
     function registerResolver(IExternalResolver resolver) external returns (ResolverUID uid);
 
     /**
-     * Entities that previously regsitered an external resolver, may update the implementation address.
+     * Entities that previously registered an external resolver, may update the implementation address.
      * @param uid The UID of the resolver.
      * @param resolver The new resolver implementation address.
      */
@@ -350,7 +361,7 @@ interface IRegistry is IERC7484 {
     function transferResolverOwnership(ResolverUID uid, address newOwner) external;
 
     /**
-     * Getter function to get the ResolverRecord of a registerd resolver
+     * Getter function to get the ResolverRecord of a registered resolver
      * @param uid The UID of the resolver.
      */
     function findResolver(ResolverUID uid) external view returns (ResolverRecord memory record);

src/Registry.sol

@@ -3,8 +3,15 @@ pragma solidity ^0.8.24;
 
 import { SignedAttestation } from "./core/SignedAttestation.sol";
 import { IRegistry } from "./IRegistry.sol";
+
 /**
- * @author zeroknots
+ * Implementation of all features of the registry:
+ *      - Register Schemas
+ *      - Register External Resolvers
+ *      - Register Modules
+ *      - Make Attestations
+ *      - Make Revocations
+ *      - Delegate Trust to Attester(s)
+ * @author rhinestone | zeroknots.eth, Konrad Kopp (@kopy-kat)
  */
-
 contract Registry is IRegistry, SignedAttestation { }

src/core/Attestation.sol

@@ -5,6 +5,11 @@ import { AttestationRecord, AttestationRequest, RevocationRequest, SchemaUID } f
 import { AttestationManager } from "./AttestationManager.sol";
 import { IRegistry } from "../IRegistry.sol";
 
+/**
+ * Abstract contract that implements the `IRegistry` interface
+ * Allows `msg.sender` to make attestations / revocations directly
+ * @author rhinestone | zeroknots.eth, Konrad Kopp (@kopy-kat)
+ */
 abstract contract Attestation is IRegistry, AttestationManager {
     /**
      * @inheritdoc IRegistry

src/core/AttestationManager.sol

@@ -22,7 +22,9 @@ import { EMPTY_ATTESTATION_REF, EMPTY_RESOLVER_UID, _time, ZERO_TIMESTAMP } from
 
 /**
  * AttestationManager handles the registry's internal storage of new attestations and revocation of attestation
- * @dev This contract is abstract and provides utility functions to store attestations and revocations.
+ * @dev This contract is abstract and provides internal utility functions to store attestations and revocations.
+ *
+ * @author rhinestone | zeroknots.eth, Konrad Kopp (@kopy-kat)
  */
 abstract contract AttestationManager is IRegistry, ModuleManager, SchemaManager, TrustManagerExternalAttesterList {
     using StubLib for *;
@@ -42,12 +44,12 @@ abstract contract AttestationManager is IRegistry, ModuleManager, SchemaManager,
      * Processes an attestation request and stores the attestation in the registry.
      * If the attestation was made for a module that was not registered, the function will revert.
      * function will get the external Schema Validator for the supplied SchemaUID
-     *         and call it, if an external IExternalSchemaValidator was set
-     * function will get the external IExternalResolver for the module - that the attestation is for
+     *         and call it, if an external `IExternalSchemaValidator` was set
+     * function will get the external `IExternalResolver` for the module - that the attestation is for
      *        and call it, if an external Resolver was set
      * @param attester The address of the attesting account.
      * @param schemaUID the UID of the schema that the attestation is made for
-     * @param request AttestationRequest send by attester via calldata
+     * @param request AttestationRequest send by attester via `calldata`
      */
     function _attest(address attester, SchemaUID schemaUID, AttestationRequest calldata request) internal {
         (AttestationRecord memory record, ResolverUID resolverUID) =
@@ -88,11 +90,11 @@ abstract contract AttestationManager is IRegistry, ModuleManager, SchemaManager,
 
     /**
      * Stores an attestation in the registry storage.
-     * The bytes encoded AttestationRequest.Data is not stored directly into the registry storage,
-     * but rather stored with SSTORE2. SSTORE2/SLOAD2 is writing and reading contract storage
+     * The bytes encoded `AttestationRequest.Data` is not stored directly into the registry storage,
+     * but rather stored with `SSTORE2`. `SSTORE2/SLOAD2` is writing and reading contract storage
      * paying a fraction of the cost, it uses contract code as storage, writing data takes the
-     * form of contract creations and reading data uses EXTCODECOPY.
-     * since attestation data is supposed to be immutable, it is a good candidate for SSTORE2
+     * form of contract creations and reading data uses `EXTCODECOPY`.
+     * since attestation data is supposed to be immutable, it is a good candidate for `SSTORE2`
      *
      * @dev This function will revert if the same module is attested twice by the same attester.
      *      If you want to re-attest, you have to revoke your attestation first, and then attest again.
@@ -128,7 +130,7 @@ abstract contract AttestationManager is IRegistry, ModuleManager, SchemaManager,
         }
 
         // use SSTORE2 to store the data in attestationRequest
-        // @dev this will revert, if in a batched attestation,
+        // this will revert, if in a batched attestation,
         // the same data is used twice by the same attester for the same module since the salt will be the same
         AttestationDataRef sstore2Pointer = request.sstore2({ salt: attester.sstore2Salt(module) });
 
@@ -155,8 +157,8 @@ abstract contract AttestationManager is IRegistry, ModuleManager, SchemaManager,
 
     /**
      * Revoke a single Revocation Request
-     * This function will write the RevocationRequest into storage, and get the stored RevocationRecord back,
-     * and pass the RevocationRecord to the resolver to check if the revocation is valid
+     * This function will write the `RevocationRequest` into storage, and get the stored `RevocationRecord` back,
+     * and pass the `RevocationRecord` to the resolver to check if the revocation is valid
      */
     function _revoke(address attester, RevocationRequest calldata request) internal {
         (AttestationRecord memory record, ResolverUID resolverUID) = _storeRevocation(attester, request);
@@ -165,8 +167,8 @@ abstract contract AttestationManager is IRegistry, ModuleManager, SchemaManager,
 
     /**
      * Revoke an array Revocation Request
-     * This function will write the RevocationRequest into storage, and get the stored RevocationRecord back,
-     * and pass the RevocationRecord to the resolver to check if the revocation is valid
+     * This function will write the `RevocationRequest` into storage, and get the stored `RevocationRecord` back,
+     * and pass the `RevocationRecord` to the resolver to check if the revocation is valid
      */
     function _revoke(address attester, RevocationRequest[] calldata requests) internal {
         uint256 length = requests.length;
@@ -182,7 +184,7 @@ abstract contract AttestationManager is IRegistry, ModuleManager, SchemaManager,
             else if (resolverUID_cache != resolverUID) revert DifferentResolvers();
         }
 
-        // No schema validation required during revocation. the attestation data was already checked against
+        // No schema validation required during revocation. The attestation data was already checked against
         records.tryExternalResolverOnRevocation({ $resolver: $resolvers[resolverUID] });
     }
 
@@ -228,8 +230,8 @@ abstract contract AttestationManager is IRegistry, ModuleManager, SchemaManager,
     }
 
     /**
-     * Returns the attestation records for the given module and attesters.
-     * This function is expected to be used by TrustManager and TrustManagerExternalAttesterList
+     * Returns a storage reference to attestation records for the given module and attesters.
+     * This function is expected to be used by `TrustManager` and `TrustManagerExternalAttesterList`
      */
     function $getAttestation(address module, address attester) internal view override returns (AttestationRecord storage $attestation) {
         $attestation = $moduleToAttesterToAttestations[module][attester];