Merge branch 'dev' into dependabot/npm_and_yarn/dev/typescript-5.8.2

Author: AdamMomen

.env.example

@@ -1,5 +1,5 @@
 # Offchain db connection string for mongodb
-DATABASE_URL="mongodb://tap:tap@localhost:27017/mongo?authSource=admin&retryWrites=true&w=majority"
+DATABASE_URL="mongodb://ocp:ocp@localhost:27017/mongo?authSource=admin&retryWrites=true&w=majority"
 DATABASE_REPLSET="0"  # set to "1" if using --replSet option in mongo. this allows transactions
 
 # RPC url for testnet (defaults to Anvil's http://127.0.0.1:8545)
@@ -20,6 +20,8 @@ ETHERSCAN_L1_API_KEY=UPDATE_ME
 PORT=8293
 
 # FACET ADDRESSES
+FACTORY_ADDRESS=
+REFERENCE_DIAMOND=
 DIAMOND_CUT_FACET=
 ISSUER_FACET=
 STAKEHOLDER_FACET=

.gitignore

@@ -29,6 +29,8 @@ yarn-error.log*
 
 !.vscode
 
+# JetBrains
+.idea/
 
 # TypeScript
 tsconfig.tsbuildinfo

README.md

@@ -1,14 +1,116 @@
-<div align="center">
-  <a href="https://github.com/victormimo/open-captable-protocol/blob/main/LICENSE">
-    <img alt="License" src="https://img.shields.io/github/license/victormimo/open-captable-protocol">
-  </a>
-</div>
+# Open Cap Table Protocol (OCP)
 
-# Documentation
+This repository implements the **Open Cap Table Protocol (OCP)** for managing cap tables on-chain. It adheres to the **Open Cap Format (OCF)** standard for data modeling and validation. OCP supports managing cap tables across multiple **EVM-compatible chains**.
 
-This repo is based on the [Open Cap Table Coalition](https://github.com/Open-Cap-Table-Coalition/Open-Cap-Format-OCF) standard, with the license included in its entirety.
+## Repo Organization
 
-## License
+-   **`src/`** → Server files (routes, MongoDB, etc.)
+-   **`chain/`** → Smart contracts (Diamond pattern with facets)
+
+## Prerequisites
+
+Ensure you have the following installed:
+
+-   [Forge](https://book.getfoundry.sh/)
+-   [Node.js](https://nodejs.org/)
+-   [Yarn](https://yarnpkg.com/)
+
+## Setup & Running Locally
+
+1. Copy `.env.example` to `.env.local`. (The example file includes a local database setup for testing, which we recommend.)
+
+### Setup
+
+1. Install dependencies:
+
+    ```sh
+    yarn install
+    ```
+
+2. You should see the factory contracts successfully deployed.
+
+3. Start services:
+
+    - **Terminal 1:** Start Anvil (local blockchain)
+        ```sh
+        anvil
+        ```
+      - Take one of the output's "Private Keys" and set your env file's `PRIVATE_KEY`
+
+    - **Terminal 2:** Deploy contracts
+        ```sh
+        yarn deploy:local
+        ```
+      - Set your env file's variables using output of deploy script
+
+          ```sh
+          DIAMOND_CUT_FACET=
+          ISSUER_FACET=
+          STAKEHOLDER_FACET=
+          STOCK_CLASS_FACET=
+          STOCK_FACET=
+          CONVERTIBLES_FACET=
+          EQUITY_COMPENSATION_FACET=
+          STOCK_PLAN_FACET=
+          WARRANT_FACET=
+          STAKEHOLDER_NFT_FACET=
+          ```
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+    - **Terminal 3:** Run the mongo instance
+        ```sh
+        docker compose up
+        ```
+
+    - **Terminal 4:** Run the backend server
+        ```sh
+        yarn dev
+        ```
+
+## Multi-Chain Support
+
+This repository supports deploying cap tables to different **EVM chains**.
+
+-   Check `/src/chains.js` and configure the required chain keys.
+-   When making API requests:
+    -   **Issuer creation** → Pass `chainId` in the request body.
+    -   **Other transactions** (e.g., creating stakeholders, issuing stock) → Pass `issuerId` in the request body.
+-   See `/src/routes` for implementation details.
+
+## Usage
+
+1. Create an **issuer** first.
+2. Add **stakeholders**, stock classes, and other relevant data.
+3. For quick testing, use the example script:
+    ```sh
+    node src/examples/testTransfer.mjs
+    ```
+
+## Resetting Local Testing
+
+If you are frequently testing locally, reset the database before redeploying:
+
+```sh
+yarn deseed
+```
+
+## Deployment
+
+Use the appropriate command to deploy contracts:
+
+-   **Local:**
+    ```sh
+    # Clear envvars in .env.local if they exist from a previous deployment
+    yarn deploy:local
+    ```
+-   **Testnet:**
+    ```sh
+    yarn deploy:testnet
+    ```
+-   **Mainnet:**
+    ```sh
+    yarn deploy:mainnet
+    ```
+
+## License
 
+This project is licensed under the MIT License. See the [`LICENSE`](LICENSE) file for details.

chain/script/DeployFactory.s.sol

@@ -20,6 +20,7 @@ import { WarrantFacet } from "@facets/WarrantFacet.sol";
 import { StakeholderNFTFacet } from "@facets/StakeholderNFTFacet.sol";
 import { AccessControl } from "@libraries/AccessControl.sol";
 import { AccessControlFacet } from "@facets/AccessControlFacet.sol";
+import { Strings } from "openzeppelin-contracts/contracts/utils/Strings.sol";
 
 library LibDeployment {
     uint256 constant FACET_COUNT = 11; // Number of enum values FacetType
@@ -56,16 +57,19 @@ library LibDeployment {
             return FacetCutInfo({ name: "DiamondLoupeFacet", selectors: selectors });
         }
         if (facetType == FacetType.Issuer) {
-            bytes4[] memory selectors = new bytes4[](2);
+            bytes4[] memory selectors = new bytes4[](3);
             selectors[0] = IssuerFacet.initializeIssuer.selector;
             selectors[1] = IssuerFacet.adjustIssuerAuthorizedShares.selector;
+            selectors[2] = IssuerFacet.issuer.selector;
             return FacetCutInfo({ name: "IssuerFacet", selectors: selectors });
         }
         if (facetType == FacetType.Stakeholder) {
-            bytes4[] memory selectors = new bytes4[](3);
+            bytes4[] memory selectors = new bytes4[](5);
             selectors[0] = StakeholderFacet.createStakeholder.selector;
             selectors[1] = StakeholderFacet.getStakeholderPositions.selector;
             selectors[2] = StakeholderFacet.linkStakeholderAddress.selector;
+            selectors[3] = StakeholderFacet.getStakeholderId.selector;
+            selectors[4] = StakeholderFacet.getStakeholderIndex.selector;
             return FacetCutInfo({ name: "StakeholderFacet", selectors: selectors });
         }
         if (facetType == FacetType.StockClass) {
@@ -155,72 +159,50 @@ library LibDeployment {
         revert("Unknown selector");
     }
 
+    function _deployedHandler(string memory envName, address addr) internal returns (address) {
+        console.log(string.concat(envName, "=", Strings.toHexString(addr)));
+        return addr;
+    }
+
     function deployFacet(FacetType facetType) internal returns (address) {
-        address facetAddress;
         if (facetType == FacetType.DiamondLoupe) {
-            facetAddress = address(new DiamondLoupeFacet());
-            console.log("DIAMOND_LOUPE_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("DIAMOND_LOUPE_FACET", address(new DiamondLoupeFacet()));
         }
         if (facetType == FacetType.Issuer) {
-            facetAddress = address(new IssuerFacet());
-            console.log("ISSUER_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("ISSUER_FACET", address(new IssuerFacet()));
         }
         if (facetType == FacetType.Stakeholder) {
-            facetAddress = address(new StakeholderFacet());
-            console.log("STAKEHOLDER_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("STAKEHOLDER_FACET", address(new StakeholderFacet()));
         }
         if (facetType == FacetType.StockClass) {
-            facetAddress = address(new StockClassFacet());
-            console.log("STOCK_CLASS_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("STOCK_CLASS_FACET", address(new StockClassFacet()));
         }
         if (facetType == FacetType.Stock) {
-            facetAddress = address(new StockFacet());
-            console.log("STOCK_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("STOCK_FACET", address(new StockFacet()));
         }
         if (facetType == FacetType.Convertibles) {
-            facetAddress = address(new ConvertiblesFacet());
-            console.log("CONVERTIBLES_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("CONVERTIBLES_FACET", address(new ConvertiblesFacet()));
         }
         if (facetType == FacetType.EquityCompensation) {
-            facetAddress = address(new EquityCompensationFacet());
-            console.log("EQUITY_COMPENSATION_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("EQUITY_COMPENSATION_FACET", address(new EquityCompensationFacet()));
         }
         if (facetType == FacetType.StockPlan) {
-            facetAddress = address(new StockPlanFacet());
-            console.log("STOCK_PLAN_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("STOCK_PLAN_FACET", address(new StockPlanFacet()));
         }
         if (facetType == FacetType.Warrant) {
-            facetAddress = address(new WarrantFacet());
-            console.log("WARRANT_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("WARRANT_FACET", address(new WarrantFacet()));
         }
         if (facetType == FacetType.StakeholderNFT) {
-            facetAddress = address(new StakeholderNFTFacet());
-            console.log("STAKEHOLDER_NFT_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("STAKEHOLDER_NFT_FACET", address(new StakeholderNFTFacet()));
         }
         if (facetType == FacetType.AccessControl) {
-            facetAddress = address(new AccessControlFacet());
-            console.log("ACCESS_CONTROL_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("ACCESS_CONTROL_FACET", address(new AccessControlFacet()));
         }
         if (facetType == FacetType.MockFacet) {
-            facetAddress = address(new MockFacet());
-            console.log("MOCK_FACET=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("MOCK_FACET", address(new MockFacet()));
         }
         if (facetType == FacetType.MockFacetV2) {
-            facetAddress = address(new MockFacetV2());
-            console.log("MOCK_FACET_V2=", facetAddress);
-            return facetAddress;
+            return _deployedHandler("MOCK_FACET_V2", address(new MockFacetV2()));
         }
         revert("Unknown facet type");
     }

chain/src/core/CapTableFactory.sol

@@ -19,7 +19,7 @@ contract CapTableFactory is Ownable {
     // Reference diamond to copy facets from
     address public immutable referenceDiamond;
 
-    constructor(address _referenceDiamond) {
+    constructor(address _referenceDiamond) Ownable(msg.sender) {
         require(_referenceDiamond != address(0), "Invalid referenceDiamond");
         referenceDiamond = _referenceDiamond;
     }

chain/src/facets/IssuerFacet.sol

@@ -7,13 +7,9 @@ import { Issuer } from "@libraries/Structs.sol";
 import { TxHelper, TxType } from "@libraries/TxHelper.sol";
 import { AccessControl } from "@libraries/AccessControl.sol";
 import { console } from "forge-std/console.sol";
+import { IIssuerFacet } from "@interfaces/IIssuerFacet.sol";
 
-contract IssuerFacet {
-    error IssuerAlreadyInitialized();
-    error InvalidSharesAuthorized();
-
-    event IssuerAuthorizedSharesAdjusted(uint256 newSharesAuthorized);
-
+contract IssuerFacet is IIssuerFacet {
     /// @notice Initialize the issuer with initial shares authorized
     /// @dev Can only be called once by an admin during setup
     function initializeIssuer(bytes16 id, uint256 initial_shares_authorized) external {
@@ -31,6 +27,10 @@ contract IssuerFacet {
         ds.issuer = Issuer({ id: id, shares_issued: 0, shares_authorized: initial_shares_authorized });
     }
 
+    function issuer() external view returns (Issuer memory) {
+        return StorageLib.get().issuer;
+    }
+
     /// @notice Adjust the total number of authorized shares for the issuer
     /// @dev Only DEFAULT_ADMIN_ROLE can adjust authorized shares
     function adjustIssuerAuthorizedShares(bytes16 id, uint256 newSharesAuthorized) external {

chain/src/facets/StakeholderFacet.sol

@@ -17,6 +17,7 @@ contract StakeholderFacet {
 
     error StakeholderAlreadyExists(bytes16 stakeholder_id);
     error AddressAlreadyLinked(address wallet_address);
+    error NoStakeholder();
 
     /// @notice Create a new stakeholder
     /// @dev Only OPERATOR_ROLE can create stakeholders
@@ -57,6 +58,23 @@ contract StakeholderFacet {
         emit StakeholderAddressLinked(stakeholder_id, wallet_address);
     }
 
+    /// @notice Get stakeholder id for a given address
+    function getStakeholderId(address wallet_address, bool ensure_exists) external view returns (bytes16) {
+        Storage storage ds = StorageLib.get();
+
+        // Check if address is linked to a stakeholder
+        bytes16 stakeholder_id = ds.addressToStakeholderId[wallet_address];
+        if (ensure_exists && stakeholder_id == bytes16(0)) {
+            revert NoStakeholder();
+        }
+        return stakeholder_id;
+    }
+
+    /// @notice Get stakeholder idx for a stakeholder id
+    function getStakeholderIndex(bytes16 stakeholder_id) external view returns (uint256) {
+        return StorageLib.get().stakeholderIndex[stakeholder_id];
+    }
+
     /// @notice Get all positions for a stakeholder
     /// @dev INVESTOR_ROLE can only view their own positions, OPERATOR_ROLE and above can view any
     function getStakeholderPositions(bytes16 stakeholder_id) external view returns (StakeholderPositions memory) {

chain/src/facets/StakeholderNFTFacet.sol

@@ -22,6 +22,13 @@ contract StakeholderNFTFacet is ERC721 {
 
     constructor() ERC721("Stakeholder Position", "STKPOS") { }
 
+    // Internal function to check if a token exists by checking if the stakeholder ID exists
+    function _exists(uint256 tokenId) internal view returns (bool) {
+        Storage storage ds = StorageLib.get();
+        bytes16 stakeholderId = bytes16(uint128(tokenId));
+        return ds.stakeholderIndex[stakeholderId] != 0;
+    }
+
     /// @notice Mint an NFT representing a stakeholder's position
     /// @dev Only stakeholders with INVESTOR_ROLE can mint their own NFT
     function mint() external {
@@ -45,7 +52,7 @@ contract StakeholderNFTFacet is ERC721 {
             revert AlreadyMinted();
         }
 
-        _mint(msg.sender, tokenId);
+        _safeMint(msg.sender, tokenId);
     }
 
     /// @notice Get the URI for a token, containing metadata about stakeholder positions

chain/src/interfaces/ICapTable.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import { IAccessControlFacet } from "./IAccessControlFacet.sol";
+import { ICapTableFactory } from "./ICaptableFactory.sol";
+import { ICapTableInitializer } from "./ICapTableInitializer.sol";
+import { IConvertiblesFacet } from "./IConvertiblesFacet.sol";
+import { IEquityCompensationFacet } from "./IEquityCompensationFacet.sol";
+import { IIssuerFacet } from "./IIssuerFacet.sol";
+import { IStakeholderFacet } from "./IStakeholderFacet.sol";
+import { IStakeholderNFTFacet } from "./IStakeholderNFTFacet.sol";
+import { IStockClassFacet } from "./IStockClassFacet.sol";
+import { IStockFacet } from "./IStockFacet.sol";
+import { IStockPlanFacet } from "./IStockPlanFacet.sol";
+import { IWarrantFacet } from "./IWarrantFacet.sol";
+
+/* Consolidation of interfaces facet internally */
+interface ICapTable is
+    IAccessControlFacet,
+    IConvertiblesFacet,
+    IEquityCompensationFacet,
+    IIssuerFacet,
+    IStakeholderFacet,
+    IStakeholderNFTFacet,
+    IStockClassFacet,
+    IStockFacet,
+    IStockPlanFacet,
+    IWarrantFacet
+{ }