Try   HackMD

Brønnøysund Captable developer documentation (beta)

Introduction

There are some 321 000 limited liability companies in Norway - less than 1000 have their shareholding listed in a securities register. While every company is obliged to keep an updated cap table, the vast majority of companies report shareholding only for tax purposes once a year.

Many people believe in a local business or a start-up, but few have the energy and insights to invest. What energy might be released if more people were able to take part in financing ideas they believe in. By providing infrastructure, we hope to establish a platform that makes ownership transparent and lower the risks of engaging with small and mediums sized enterprises. Doing so is part of a broad effort to make capital more efficient, for example, by making shares liquid, allowing their use as collateral and link loans, mortgages, and payments direct to shares and share transactions. In the process, it is quite possible to imagine a greatly simplified public reporting where regulators may themselves access the required data - and a greatly simplified corporate governance involving share loyalty programs, the payment of dividends and voting. In short, the platform may serve to open and democratizing the unlisted markets for new groups of investors.

Norwegian limited liability companies must have a share capital of at least NOK 30,000 assigned to one or more shares, each of identical nominal value. The total share capital, the number of shares, and their nominal value is stated in the company's articles of association.

All limited liability companies shall have a register of shareholders unless the company's shares are registered in a securities register. The cap table shall contain an overview of the company's shareholders, and it will typically determine who may exercise shareholder rights, including the right to vote at the general meeting and the right to receive dividends. The cap table is, in principle, public - insight should not be denied.

What is a cap table?

Upon listing a shareholder in the shareholders' register, the company shall notify the shareholder thereof. The shareholders' register shall be updated in accordance with established rules in the Companies Act (§ 4-7) to reflect changes of ownership or pledging of shares. Shares can be sold or given away without payment unless otherwise stated by law, articles of association or agreement between the shareholders. In the case of a sale, the price is usually calculated based on market value. Transfers of ownership below market value are referred to as "gift sale" and may trigger a tax liability. When shareholders sell or otherwise realize shares, gains will be taxable and losses deductible. The Companies Act contains rules on the consent of acquiring shares, and rules on pre-emption rights for the other shareholders. An agreement to transfer shares shall be reported to the board of the limited company by the person acquiring the shares. The agreement should, as a minimum, list all the parties, the number of shares to be transferred, and at what price. Transfers in BrregCapTable will be reported automatically. The new shareholder must be notified by the company that she has been included in the shareholders' register and what is listed.

Companies and shareholders that rely on BrregCapTable may need not keep a separate cap table nor report its details to the government as everything is automated.

Shareholder agreements

Shareholder agreements are normally entered into between shareholders of a company and regulate the relationship between them. Shareholders are not obliged to enter into such an agreement, but it may be useful. A shareholder agreement obliges only the shareholders who have signed the agreement. There are no requirements as to how the agreement should look or what it should contain. Examples of conditions that can be regulated in a shareholder agreement are rules relating to ownership, demands for dividends, non-compete clauses, impartiality, and work/employment requirements.

Conflict between shareholders

It is not uncommon for conflicts between shareholders to arise regarding the organization and running of a company. Since the causes of conflict may be difficult to spot in advance, it may make sense to

  • Avoid a setup where two owners hold 50% of the shares each and hence become incapable of making majority decisions in cases of conflict
  • Enter into shareholder agreements that clarify how the relationship between shareholders in the event of disagreement.

In cases where the shareholders no longer manage to cooperate with each other, the district court may, in response to a lawsuit from a shareholder or from the company, decide on the redemption or release of a shareholder's shares. Such lawsuits must be regarded as last resort, and there must be weighty reasons.

Smart contracts

Captable contract

Captable is a smart contract protocol following the ERC1400 standard. The implementation heavily utilizes and are interoperatbleConsensys 1400 implementation.

Create Captable

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →

Captable extensions

There are mainly four ways to extend or hook into the Captable protocol.

CDP Property Trade

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →

In this example, a property owner collateralizes his property. This token of ownership but dependent on collateralization can then be utilized in a system for exchange.

This example heavily utilizes hooks so that independent entities can exchange tokens.

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →

Que

Que works as a filter for the registry. This is where Brreg receives issues for new registrations. Then verifies and process them into the registry.

The Captable template automatically inserts the captable into que.

https://gitlab.com/brreg1/captable/-/blob/master/contracts/CapTableQue.sol

Registry

Registry is where approved Captables go. This is the public registery that all services should use and follow.

https://gitlab.com/brreg1/captable/-/blob/master/contracts/CapTableRegistry.sol

Multisig

For shared ownership. Will be extended upon in the future.

https://gitlab.com/brreg1/captable/-/blob/master/contracts/MultiSigWallet.sol

Deployment addresses

AUTH_ORACLE='0x4A6Ecc8631990741263b38EEB434405C04CDc723'
ERC1820='0x7C2F9F4A231F37BA7321D56B19909c8FE5dFd144'
QUE='0xD6fD724617D63bc7d8347770f1495706aff622b0'
REGISTRY='0x894f201a7b7E5B42e0840C9797fd42C6
PROPERTY_PLATTFORM='0xEC0712a5c12cFEE4F39b1D7E0903bf6098b8c54D'
PROPERTY_REGISTRY='0xf9Bcfd9F56F4D9061dF42FB011DC04958eAcD32d'
TRADE_REGISTRY='0xBd9F1aaa4aCB569996352376262b7Dec770B1683'
MORTGAGE_REGISTRY='0xA4f5f570700DE2Bee9b773422CD04A9439AA20Df'

Deploy everything yourself

  1. AuthOracle-Contracts
    1. npm run deploy::brreg
    2. Kopier ned følgende addresser

REACT_APP_AUTH_ORACLE='0x123'

  1. AuthOracle
    1. Endre .env.production sin auth oracle addresse
    2. Push changes, CI will deploy new version in Vercel https://vercel.com/robertosnap/auth-oracle
  2. CapTable-Contracts
    1. Change buidler.config.js object. Deploy property. Under networkId (brreg er 1733917133) add key => value with authOracle: '0x123',
    2. Image Not Showing Possible Reasons
      • The image file may be corrupted
      • The server hosting the image is unavailable
      • The image path is incorrect
      • The image format is not supported
      Learn More →
    3. npx buidler deploy --network brreg
    4. Copy down addresses

REACT_APP_ERC1820='0x123'
REACT_APP_QUE='0x123'
REACT_APP_REGISTRY='0x123'

  1. Forvalt
    1. Change .env.production with addresses copied from AuthOracle og CapTable deploy. Overwrite what is there.
    2. Push changes, CI will deploy new version in Gitlab: https://gitlab.com/blockchangers/cloudless/aksjelisten/pages
  2. Eierskifte-Contracts
    6. In this repo, there is a test that deploys the system. But we need to update this test file with the new addresses:
    7. test/PropertyRegistry.ts :88 copy in addresses under networkId for erc1820, Que, AuthOracle
    8. npx buidler test --network brreg
    9. Copy down

REACT_APP_PROPERTY_PLATTFORM='0x123'
REACT_APP_PROPERTY_REGISTRY='0x123'
REACT_APP_TRADE_REGISTRY='0x123'
REACT_APP_MORTGAGE_REGISTRY='0x123'

  1. Eierskifte-web
    10. Change .env.production with addresses copied from AuthOracle, CapTable, Eierskifte-contracts deploy. Overskriv de som allerede er der.
    2. Push changes, CI will deploy new version in Gitlab: https://gitlab.com/blockchangers
  2. Visma-Boardroom
    10. Change .env.production with addresses copied from AuthOracle, CapTable deploy. Overskriv de som allready er der.
    2. Push changes, CI will deploy new version in Gitlab: https://gitlab.com/blockchangers

Apps

Backend frontend oversukt

Brønnøysund

Visma

OBOS

Other

If you have created an application and want it listed here, contact Jon at blockchangers.com

Integrate your app

Integrate frontend

Setup

Want to just get going? Jump to Quikstart

As Brreg Captable is a service facilitated by blockchain technology, end-users will interact with your service in ways that differ from a regular client-server approach.

Instead of credentials authenticating the user and giving the user the correct access, end users are expected to use a browser with blockchain wallet functionality. This functionality is available in

  • Google Chrome, Firefox, Brave and Microsoft Edge when installing the Metamask plugin
  • The Opera web browser

As a frontend developer, you must download this plugin and use it when developing frontend applications.

Metamask

In the top-right menu of MetaMask, you can select the network that you are currently connected to. Among several popular defaults, you'll find Custom RPC. Use it and set

  1. Network Name to Brreg (it's not important what you call it, just for your own reference)
  2. New RPC URL to https://u1ps4u882p:zGyIQRNUcAMSaxI79_LhovZLakJ8127sDGDABVhdgAE@u1txh1ent0-u1ieecy018-rpc.us1-azure.kaleido.io

Since your seed phrase is the power to control all your accounts, it is probably worth keeping at least one seed phrase for development, separate from any that you use for storing real value. One easy way to manage multiple seed phrases with MetaMask is with multiple browser profiles, each of which can have its own clean extension installations.

Note that users of your application will have to connect Metamask to the Brreg network, too, while BrregCapTable remains in development as a beta.

Metamask / web3 details

There are settings you should keep in mind when interacting with Metamask:

  • What is the current network?
  • What is the current account?























































































































































ethereum.networkVersion
ethereum.selectedAddress
`"

> When you're ready to request the user log in, you can call this simple function.

```javascript=
ethereum.enable();

`"

> Since it returns a promise, if you're in an `async` function, you may log in like this.

```javascript=
const accounts = await ethereum.enable()
const account = accounts[0] // We currently only ever provide a single account,
                            // but the array gives us some room to grow.
`"
:::info
If the networkVersion is not **1733917133**, the user is not connected to the Brreg Network. Guide the user to correcting this.
:::

#### User provider package
Instead of handling all this Ethereum....web3...metamask things ourselves, let us add the package [web3Modal](https://github.com/Web3Modal/web3modal) which can handle it for us. 

```javascript=
npm install --save web3modal

# OR

yarn add web3modal

`"
Then add this to your js/ts app
```javascript=
import Web3Modal from "web3modal";

const web3Modal = new Web3Modal({
  network: "mainnet", // optional
  cacheProvider: true, // optional
  providerOptions: {} // required
});

const provider = await web3Modal.connect();

`"

Now you got a provider to interact with Brreg network.  This provider will respond to request for Block numbers, transactions request, and so on. But we want to interact with smart contracts easily. To do this effortlessly, we include a library like [ethers.js](https://github.com/ethers-io/ethers.js/) or [web3.js](https://github.com/ethereum/web3.js/). 


#### Provider library

We use something called Buidler.dev and Typechain to generate typescript definitions from smart contracts. This will then type check our input and response variables as well as list and suggest functions available in your smart contracts when developing. This requires an older version of Ethers, so let's install

`"
npm install --save ethers@4.0.47

# OR

yarn add ethers@4.0.47
`"

Then let's create a TS file so that we can effortlessly get an ethers web3 provider


```typescript=
// utils/web3.ts
import Web3Modal, { IProviderOptions } from "web3modal";
import { ethers } from "ethers";
import { JsonRpcSigner, Web3Provider } from "ethers/providers";

export const getWeb3 = async (): Promise<JsonRpcSigner> => {
  const web3ModalProvider = await getNativeProvider();
  const web3provider = new ethers.providers.Web3Provider(web3ModalProvider as Web3Provider);
  return await web3provider.getSigner();
};

export const getNativeProvider = async () => {
  const providerOptions: IProviderOptions = {};
  const web3Modal = new Web3Modal({
    cacheProvider: true,
    providerOptions, 
  return await web3Modal.connect();
};

export const TX_OVERRIDE = () => {
  return {
    gasPrice: ethers.utils.parseUnits("0.0", "gwei"),
    gasLimit: 7999999,
  };
};
`"

#### Interact with smart contract
Now that we got our provider setup, we need to give the provider an interface to the smart contract. 

You can get interfaces for Captable here: https://gitlab.com/brreg1/captable/-/releases download the tar.gz or zip and put files ./contracts 


```typescript=
// utils/contracts.ts
import { getWeb3 } from   "./web3";

import { CapTableFactory } from   "../contracts/CapTableFactory";
import { CapTable } from   "../contracts/CapTable";

export const getCapTable = async (capTableAddress: string) => {
  return CapTableFactory.connect(capTableAddress, await getWeb3());
};

export const useCapTable = (
  capTableAddress: string
): [CapTable | undefined, boolean, string] => {
  const [contract, setContract] = useState<CapTable>();
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState("");
  useEffect(() => {
    getCapTable(capTableAddress)
      .catch((err) => handleError(err, setError))
      .then((_contract) => {
        setLoading(false);
        setContract(_contract);
      });
  }, [capTableAddress, error]);
  return [contract, loading, error];
};

const handleError = (error: any, handler: (err: string) => void) => {
  if (error) {
    if (error.hasOwnProperty("message")) {
      handler(error.message);
    } else {
      handler(error);
    }
  } else {
    handler("Udefined error");
  }
  return undefined;
};
`"


### Quickstart
1. Install
```javascript=
npm install --save web3modal ethers@4.0.47

# OR

yarn add web3modal ethers@4.0.47
  1. Create folder utils
  2. Create TS file contracts.ts inside utils. contents
  3. Create TS file web3.ts inside utils. contents
  4. Create folder contracts
  5. Downlaod from Gitlab Captable to /contracts/ folder
  6. Run it






































// run.ts
import { getCapTable } from   '../../utils/contracts';

export const run = async () => {
    const [capTable] = getCapTable(address)
    if(capTable){
        const owner = await capTable.owner()
        console.log("owner =", owner)
    }
}
run()
`"

## Integrating backend
If you are creating a backend application and then don't have a provider within Metamask etc. you can connect directly to the node with ethers library.

```typescript=
    const privateKey = process.env.PRIVATE_KEY || "set env"; // 0xbb1c879cb7f5129ba026DfE1E5f30979D7978A65
    const wallet = new ethers.Wallet(privateKey);
    const provider =
      process.env.NODE_ENV === "production"
        ? new ethers.providers.JsonRpcProvider({
            url: process.env.PROVIDER_URL || "set env",
            user: process.env.PROVIDER_USER || "set env",
            password: process.env.PROVIDER_PASS || "set env",
          })
        : new ethers.providers.JsonRpcProvider({
            url: process.env.PROVIDER_URL || "set env,
          });

    const signer = wallet.connect(provider);

    const authOracle = new AuthOracleFactory(signer).attach(
      process.env.AUTH_ORACLE_ADDRESS || "set env"
    );
`"
Last changed by 
 
Brreg
Brreg
0
535
Published on HackMD