Skip to content

Latest commit

 

History

History
153 lines (96 loc) · 6.82 KB

README.md

File metadata and controls

153 lines (96 loc) · 6.82 KB
Raw

BRØK

Overview

BRØK is a cutting-edge service developed for sharing shareholder information. It connects shareholder registers using blockchain technology, making ownership information easily accessible to financial institutions, the press, public agencies, and other service providers.

With 380,000 corporations maintaining their shareholder books, BRØK aims to create a single platform that enables the transparent and efficient exchange of information.

Features

  • First-time publishing of information from the shareholder book
  • Transfer of shares (existing/new shareholders)
  • Managing shareholder information
  • Information about the assignment/deletion of shares related to company events
  • Information about share pledges
  • Reading the latest version of the shareholder book

Architecture

BRØK's architecture includes three key components:

  • Blockchain: Rules defined by smart contracts 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.
  • 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.

Quick setup

Requirements

  • curl
  • Docker (or Podman) with docker-compose
curl -sSL https://raw.githubusercontent.com/brreg/brok/v6/quick-setup.sh | bash

Development

Requirements

  • Node
  • pnpm
  • Hardhat
  • Compatible container orchestration systems such as Docker or Podman

Environment Variables Setup

The Captable package

Firstly, create a .env file in packages/captable by copying the .env.example file:

cp packages/captable/.env.example packages/captable/.env

Then, update the .env file with the correct values for your environment.

Below are the key settings required for system operation. You should set these variables based on your specific configuration and requirements.

  • ETHERSCAN_API_KEY: Your personal Etherscan API key is used for verifying smart contracts (e.g., 1234567890ABCDEF).

  • SEED_DEV, SEED_STAGE, SEED_PROD: Seed phrases for the development, staging, and production environments, respectively (e.g., test test test test test test test test test test test junk).

  • RPC_TESTNET: The HTTP URL of the testnet Ethereum RPC node (e.g., http://127.0.0.1:8545/).

  • RPC_MAINNET: The HTTP URL of the mainnet Ethereum RPC node with your personal Etherscan API key if using Infura or Alchemy (e.g., https://arb.g.alchemy.com/v2/ABC123…).

  • REPORT_GAS: A flag to control the reporting of gas consumption (e.g., false).

  • DEV_ENTERPRISE_SYSTEM_ADDRESS: The Ethereum address for the enterprise system in the development environment (e.g., "0x0a123...").

Caution: Sensitive environment variables such as seed phrases and private keys should be kept secure. Never commit them into source control.

The API package

Create a .env file in packages/api by copying the .env.example file:

cp packages/api/.env.example packages/api/.env

Then, update the .env file with the correct values for your environment. If you need a new private key, you can generate one using the following command:

node packages/api/createWallet.js

Below are the necessary environment variables that need to be configured for the proper operation of the system. You should set these variables based on your specific configuration and requirements.

  • PRIVATE_KEY: The hexadecimal representation of a private key used for signing transactions and managing an Ethereum account. (e.g., 0xSOME_PRIVATE_KEY_HEX).

  • RPC_URL: The HTTP URL of the Ethereum RPC node that your application communicates with. This URL connects your application to the Ethereum network (e.g., "http://127.0.0.1:8545").

  • PORT: The port number on which the application is set to run. This variable specifies the desired port for hosting the application (e.g., 4000).

Please ensure that these environment variables are set correctly in your system. Misconfiguration of these variables may lead to unexpected behavior or errors in the application.

Caution: Sensitive environment variables such as seed phrases and private keys should be kept secure. Never commit them into source control.

Running Locally

Follow the detailed instructions to compile smart contracts (contractual rules programmed into the system), start the local Ethereum blockchain, add demo data, start The Graph servers, and launch the API Server.

First, install dependencies:

pnpm install

Build the smart contracts:

pnpm --filter @brok/captable hardhat compile --force
pnpm --filter @brok/captable build

👩‍💻 Running locally with VSCode tasks (preferred)

In VScode, run task deploy-local (⇧⌘P Task: Run task).

This will do the following:

  • Compile smart contracts with Hardhat in ./packages/captable/contracts
  • Initializes a local version of an Ethereum blockchain
  • Populate the local network with example data from ./packages/captable/tasks/demo-cap-table.ts
  • Starts The Graph servers, with spec from ./packages/graph
  • Starts API Server from ./packages/api

Note: Data is temporarily stored and will be erased if the system is restarted. If you want to have data that persists between runtime, add them to ./packages/captable/tasks/demo-cap-table.ts

Testing

  • Ensure you're in the appropriate directory (packages/api) before initiating tests. Also, note that some kind of race condition exists in the tests, so one test file at a time has to be run individually for the time being.
  • Also note that you need to have the deploy-local VSCode task running before running the tests.
Determine contract sizes

To determine smart contract sizes the 'Hardhat Contract Sizer' can be used.

Installation

npm install --save-dev hardhat-contract-size

Usage

See the file packages/captable/hardhat.config.js for default configuration.

Run the following to print the compiled contract sizes:

npx hardhat size-contracts

Workarounds

  • To address key management issues, we've implemented a secure alternative approach (ED25519 is derived from secp256k1 private key).