brreg · ohatland · Jan 25, 2024 · Jan 25, 2024 · Jan 26, 2024 · Jan 26, 2024
diff --git a/.gitignore b/.gitignore
@@ -11,6 +11,7 @@ __pycache__
 artifacts
 lib
 typechain
+subgraph.yaml
 
 # dependencies
 node_modules

diff --git a/README.md b/README.md
@@ -18,12 +18,11 @@ With 380,000 corporations maintaining their shareholder books, BRØK aims to cre
 
 ## Architecture
 
-BRØK's architecture includes three key components:
+BRØK's architecture includes four key components:
 - **Blockchain**: Rules defined by [smart contracts](https://no.wikipedia.org/wiki/Smart_kontrakt) and secure references to ownership. See `packages/captable`
 - **TheGraph**: Enables efficient data queries from the blockchain. See `packages/graph`
 - **API**: Allows secure data access and updates through standard web technology. See `packages/api`
 - **BR Name Service**: Provides a [service for looking up BRØK addresses](https://github.com/brreg/brok-navnetjener).
-- **Fagsystem DEMO**: Integrates with BRØK, enabling the publishing of ownership details. Without a front-end like this, BRØK is not useful. [Here's an example of a front-end for a fagsystem.](https://github.com/brreg/brok-fagsystem-demo)
 
 
 # Quick setup

diff --git a/docker-compose.yaml b/docker-compose.yaml
@@ -75,7 +75,7 @@ services:
     depends_on:
     - hardhat
     environment:
-      CONTAINER_HARDHAT: http://hardhat:8545
+      RPC_CONTAINER: http://hardhat:8545
     command: ["sh", "-c", "sleep 15 && pnpm -F @brok/captable hardhat-deploy-contracts-container && pnpm -F @brok/captable hardhat-add-demo-data-container"]
   postgres:
     image: postgres

diff --git a/packages/api/README.md b/packages/api/README.md
@@ -0,0 +1,57 @@
+# Brøk API
+Creates a simplified interface for enterprise systems, so they can use BRØK without the need for any knowledge or system implementation of web3 technologies.
+
+Built with Next.js framework.
+
+Remember to complete the steps described [here](./../../README.md#development) before running this application the first time.
+
+The chapter on .env describes how this application is configured to connect to other application.
+
+
+## Application endpoints overview
+
+``/api/health`` Checks the status for the external connection, and ethereum balance
+
+``/api/checkTransaction`` Checks the status of a transaction
+
+``/api/v1/company/`` Control the CapTable for a company
+
+``/api/v1/person/`` Get the ownership information for a person or company owning shares
+
+For more explanation, check out the [swagger file](./../../docs/swagger.yaml)
+
+
+## External applications
+
+This application depends on the following to work properly:
+- an Ethereum network, either Hardhat network running locally, or Arbitrum Goerli/Sepolia/One
+- The Graph subgraph for CapTableRegistry
+- Navnetjener API
+
+To start Hardhat network and The Graph services locally, run the vs code task `deploy-local`
+
+To start Navnetjener, follow [these instructions](https://github.com/brreg/brok-navnetjener#development-setup)
+
+
+## .env
+The .env files uses the following values:
+
+| **Value** | **Description** |
+|--|--|
+| `PRIVATE_KEY`     | The Private key for the wallet used by Brøk API, intended to be provided by Brønnøysundregistrene in the future |
+| `RPC_LOCAL`       | Network address to the Hardhat network |
+| `RPC_SEPOLIA`     | Network address to the Arbitrum Sepolia network |
+| `RPC_GOERLI`      | Network address to the Arbitrum Goerli network |
+| `RPC_ONE`         | Network address to the Arbitrum One network |
+| `PORT`            | Port for the API |
+| `NAVNETJENER_URL` | URL to Navnetjener API |
+| `BROK_ENV`        | Selects Ethereum network, valid arguments: `localhost`, `brokStage` or `brokProd` |
+| `DEBUG`           | Select what part of the application you want to debug, default to `brok*` for the whole application |
+| `THE_GRAPH_URL`   | URL to The Graph subgraph |
+
+
+# Development
+
+Start dev server: `pnpm run dev`
+
+Run all tests: `pnpm run test`
diff --git a/packages/captable/.env.example b/packages/captable/.env.example
@@ -6,7 +6,7 @@ SEED_PROD=test test test test test test test test test test test junk
 RPC_CONTAINER=http://host.docker.internal:8545
 RPC_LOCAL=http://127.0.0.1:8545
 RPC_TESTNET=http://127.0.0.1:8545
+RPC_STAGENET=http://127.0.0.1:8545
 RPC_MAINNET=http://127.0.0.1:8545
 REPORT_GAS=false
-CAP_TABLE_REGISTRY_brokDev=0x8EF52e971B7Aa8f263A7C25b0F4e200709287A30
-DEV_ENTERPRISE_SYSTEM_ADDRESS=0x0a665B1Bc813cAE9fcDd2Eb7E25b8E55A5F35f23
+DEV_ENTERPRISE_SYSTEM_ADDRESS=0x4cCE8E0e2Ba902FE7D2D1fD894d85883E7cd720d
diff --git a/packages/captable/README.md b/packages/captable/README.md
@@ -1,4 +1,55 @@
 # Smart contracts for CapTable BRØK
 
-NB! brokProd is still against Arbitrum Goerli
+Smart contracts for CapTable and CapTableRegistry developed in [Solidity v0.8.0](https://docs.soliditylang.org/en/v0.8.0/)
 
+Based on [ERC1400](https://consensys.io/staking/assets/universal-token), but intended to migrate to [ERC3643](https://www.erc3643.org/) in the future.
+
+The contracts are built and tested with [Hardhat](https://hardhat.org/hardhat-runner/docs/getting-started#overview)
+
+Based on the generated contracts, [tsup](https://www.npmjs.com/package/tsup) is used to generate a TypeScript library, to be used by Brøk API and The Graph configuration.
+
+***Note: 'brokProd' is currently configured to run on the deprecated Arbitrum Goerli network. In future versions we might transition to Sepolia.***
+
+## Project overview
+
+| **Folder** | **Description** |
+|--|--|
+| `artifacts/` | Compiled artifacts generated by Hardhat compile (generated) |
+| `cache/` | The directory used by Hardhat to cache its internal stuff (generated) |
+| `contracts/` | CapTable and CapTableRegistry contracts in Solidity, with dependencies |
+| `deployments/` | Our way to persist smart contract addresses deployed on Arbitrum, generated by [./tasks/generate-deployments.ts](./tasks/generate-deployments.ts) |
+| `dist/` | Generated TypeScript library of CapTable and CapTableRegistry (generated) |
+| `scripts/` | I dont know what this does |
+| `tasks/` | Hardhat tasks to be run with ``hardhat <task name> --network <network name> --log``
+| `test/` | Tests for CapTable and CapTableRegistry |
+| `typechain-types/` | Generated TypeScript bindings for smart contracts (generated) |
+
+
+### .env
+| **Value** | **Description** |
+|--|--|
+| `ETHERSCAN_API_KEY` | Used for verifying that the contract's source code matches the executed bytecode onchain, makes the source code viewable on Etherscan and makes it possible to execute smart contract functions directly from Etherscan. |
+| `SEED_DEV` | Mnemonic key for Brønnøysundregistrenes wallet used to deploy contracts in the dev environment |
+| `SEED_STAGE` | Mnemonic key for Brønnøysundregistrenes wallet used to deploy contracts in the stage environment |
+| `SEED_PROD` | Mnemonic key for Brønnøysundregistrenes wallet used to deploy contracts in the production environment **NB: contains real money** |
+| `RPC_CONTAINER` | Network address to Hardhat network running with `docker-compose` |
+| `RPC_LOCAL` | Network address to Hardhat network running local |
+| `RPC_TESTNET` | Network address to the Arbitrum Goerli network |
+| `RPC_STAGENET` | Network address to the Arbitrum One network |
+| `RPC_MAINNET` | Network address to the Arbitrum One network |
+| `CONTRACT_SIZER` | Boolean for turning on verbose compilation where contract sizes are being outputted when they are compiled. |
+| `REPORT_GAS` | Same as `CONTRACT_SIZER` but with finer granularity output. This outputs gas used for each test and every smart contract method |
+| `DEV_ENTERPRISE_SYSTEM_ADDRESS` | Give this wallet address the permission to publish CapTables to the CapTableRegistry |
+
+
+## Hardhat networks
+There are several hardhat networks configured in [hardhat.config.ts](./hardhat.config.ts#L83). These networks are configured to use a url from the .env file `RPC_*` and mnemonic frases, `SEED_*`, to access the account on the network used to deploy the smart contracts.
+
+**Be very careful about the `SEED_PROD` because this wallet holds real money, they will be quickly stolen if the key is leaked to the public!**
+
+These networks are used in the Hardhat cli as `hardhat --network <network name>` e.g. `hardhat --network brokStage`
+
+## Deployment prosess
+To deploy the smart contracts to production, run `pnpm hardhat-deploy-contracts-production`,
+
+Again, make sure the `.env` file holds the correct values **before** running this command
diff --git a/packages/captable/scripts/deploy.ts b/packages/captable/scripts/deploy.ts
diff --git a/packages/graph/README.md b/packages/graph/README.md
@@ -1,7 +1,28 @@
-# DEV
+# Search indexing for CapTableRegistry BRØK
 
-Make sure the correct CapTableRegistry is sert in config
+The Graph is an indexing protocol for organizing blockchain data and making it easily accessible with GraphQL.
 
-Create a subgraph at https://thegraph.com/legacy-explorer/
+The Graph makes it possible to query data that is difficult to query directly.
 
-Change the NPM command to reflect new subgraph, then run `yarn run brokDev:deploy`
+The Graph learns what and how to index Ethereum data based on subgraph descriptions, known as the subgraph manifest. The subgraph description defines the smart contracts of interest for a subgraph, the events in those contracts to pay attention to, and how to map event data to data that The Graph will store in its database.
+
+Once you have written a `subgraph manifest`, you use the Graph CLI to store the definition in IPFS and tell the indexer to start indexing data for that subgraph.
+
+This diagram gives more detail about the flow of data once a subgraph manifest has been deployed, dealing with Ethereum transactions:
+
+
+## Project overview
+
+| **Folder** | **Description** |
+|--|--|
+| `abis/` | ABIS files for CapTable and CapTableRegistry, ***NB: These files are generated and copy manually*** |
+| `build/` | Generated files from `graph codegen && graph build`, based on the content of `subgraph.yaml` |
+| `docker-compose/` | Specs for running TheGraph locally with Docker compose |
+| `generated/` | Some manually generated files @jon ? |
+| `podman-compose/` | Specs for running TheGraph locally with Podman compose
+| `scripts/` | Takes constant variables from `packages/captable/deployment/` and creates `subgraph.yaml` |
+| `src/` | Some more files copy @jon ? |
+| `tests/` | I dont know @jon ? |
+
+## Deployment prosess
+To deploy subgraph to The Graph hosted services. update the deployment name in `package.json` and run one of the `deploy:*` commands