feat: added contracts and tests

.env.example

@@ -0,0 +1,31 @@
+# GENERAL
+
+## The network used for testing purposes
+NETWORK_NAME="mainnet" #  ["mainnet", "goerli", "polygon", "polygonMumbai"]
+
+# CONTRACTS
+
+## Hex encoded private keys separated by a comma `,`a
+PRIVATE_KEY="0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" # Default hardhat account 0 private key. DON'T USE FOR DEPLOYMENTS
+
+## Infura credentials
+INFURA_API_KEY="zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"
+
+## Gas Reporting
+REPORT_GAS='true'
+COINMARKETCAP_API_KEY="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
+
+## Block explorers
+ETHERSCAN_API_KEY="zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"
+POLYGONSCAN_API_KEY="zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"
+BASESCAN_API_KEY="zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"
+
+# SUBGRAPH
+
+## The Graph credentials
+GRAPH_KEY="zzzzzzzzzzzz"
+
+## Subgraph
+SUBGRAPH_NAME="osx"
+SUBGRAPH_VERSION="alice-debug-1s"
+SUBGRAPH_NETWORK_NAME="goerli" #  ["mainnet", "goerli", "polygon", "polygonMumbai"]

.github/workflows/contracts-tests.yml

@@ -0,0 +1,39 @@
+name: 'contracts'
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'contracts/**'
+      - '.github/workflows/contracts-*.yml'
+
+jobs:
+  formatting-linting:
+    uses: ./.github/workflows/formatting-linting.yml
+  tests:
+    runs-on: 'ubuntu-latest'
+    defaults:
+      run:
+        working-directory: contracts
+    steps:
+      - name: 'Check out the repo'
+        uses: 'actions/checkout@v3'
+
+      - name: 'Install Node.js'
+        uses: 'actions/setup-node@v3'
+        with:
+          cache: 'yarn'
+          node-version: 18
+
+      - name: 'Install the dependencies'
+        run: 'yarn install'
+
+      - name: 'Build the contracts'
+        run: 'yarn build'
+        env:
+          INFURA_API_KEY: ${{ secrets.INFURA_API_KEY }}
+
+      - name: 'Test the contracts and generate the coverage report'
+        run: 'yarn coverage >> $GITHUB_STEP_SUMMARY'
+        env:
+          INFURA_API_KEY: ${{ secrets.INFURA_API_KEY }}

.github/workflows/formatting-linting.yml

@@ -20,11 +20,17 @@ jobs:
       - name: 'Install the dependencies'
         run: 'yarn install'
 
-      - name: 'Install subgraph dependencies'
-        run: 'cd subgraph/ && yarn install'
-
-      - name: 'Lint subgraph'
-        run: 'yarn lint:subgraph:ts >> $GITHUB_STEP_SUMMARY'
-
       - name: 'Check code formatting'
         run: yarn prettier:check
+
+      - name: 'Lint contracts solidity'
+        run: yarn lint:contracts:sol >> $GITHUB_STEP_SUMMARY
+
+      - name: 'Lint contracts ts and js'
+        run: yarn lint:contracts:ts >> $GITHUB_STEP_SUMMARY
+
+      #- name: 'Lint js-client ts and js'
+      #  run: yarn lint:js-client:ts >> $GITHUB_STEP_SUMMARY
+
+      - name: 'Lint subgraph ts and js'
+        run: yarn lint:subgraph:ts >> $GITHUB_STEP_SUMMARY

.github/workflows/subgraph-tests.yml

@@ -1,28 +1,39 @@
-name: Subgraph
+name: 'subgraph'
+
 on:
+  workflow_dispatch:
   push:
     paths:
+      - 'contracts/**'
       - 'subgraph/**'
       - '.github/workflows/subgraph-*.yml'
 
-env:
-  working-directory: subgraph
-
 jobs:
   formatting-linting:
     uses: ./.github/workflows/formatting-linting.yml
   tests:
-    runs-on: ubuntu-latest
+    runs-on: 'ubuntu-latest'
     defaults:
       run:
-        working-directory: ${{env.working-directory}}
+        working-directory: subgraph
     steps:
-      - uses: actions/checkout@v2
-      - name: Install node
-        uses: actions/setup-node@v3
+      - name: 'Check out the repo'
+        uses: 'actions/checkout@v3'
+
+      - name: 'Install Node.js'
+        uses: 'actions/setup-node@v3'
         with:
-          node-version: 16
-      - name: Install dependencies
-        run: yarn install --pure-lockfile
-      - name: Run Tests
-        run: yarn run coverage >> $GITHUB_STEP_SUMMARY
+          cache: 'yarn'
+          node-version: 18
+
+      - name: 'Install the dependencies'
+        run: 'yarn install'
+
+      #- name: 'Build the subgraph'
+      #  run: 'yarn build'
+      #  env:
+      #    INFURA_API_KEY: ${{secrets.INFURA_API_KEY}}
+      #    NETWORK_NAME: 'goerli'
+
+      - name: 'Test the subgraph'
+        run: 'yarn test >> $GITHUB_STEP_SUMMARY'

.gitignore

@@ -33,6 +33,7 @@ yarn-error.log*
 
 # generated
 generated
+reference-guide
 .bin
 coverage.json
 .latest.json

.solhint.json

@@ -0,0 +1,19 @@
+{
+  "extends": "solhint:recommended",
+  "plugins": ["prettier"],
+  "rules": {
+    "code-complexity": ["error", 8],
+    "compiler-version": ["error", ">=0.8.4"],
+    "func-visibility": ["error", {"ignoreConstructors": true}],
+    "max-line-length": ["off", 120],
+    "named-parameters-mapping": "warn",
+    "no-console": "off",
+    "not-rely-on-time": "off",
+    "prettier/prettier": [
+      "error",
+      {
+        "endOfLine": "auto"
+      }
+    ]
+  }
+}

.solhintignore

@@ -0,0 +1,3 @@
+# directories
+**/artifacts
+**/node_modules

contracts/.eslintrc.yml

@@ -0,0 +1,18 @@
+parser: '@typescript-eslint/parser'
+parserOptions:
+  project: './contracts/tsconfig.json'
+
+# Custom eslint settings for the contracts can be defined here
+ignorePatterns:
+  # directories
+  - .coverage_artifacts
+  - .coverage_cache
+  - .coverage_contracts
+  - artifacts
+  - build
+  - cache
+  - coverage
+  - dist
+  - typechain
+  # files
+  - coverage.json

contracts/.solcover.js

@@ -0,0 +1,7 @@
+module.exports = {
+  istanbulReporter: ['html', 'lcov'],
+  providerOptions: {
+    privateKey: process.env.PRIVATE_KEY,
+  },
+  skipFiles: ['test'],
+};

contracts/docs/templates/common.hbs

@@ -0,0 +1,35 @@
+{{h 2}} {{visibility}} {{toLowerCase type}} {{name}}
+
+{{{natspec.notice}}}
+
+{{#if signature}}
+```solidity
+{{{signature}}} 
+```
+{{/if}}
+
+{{#if natspec.params}}
+| Input | Type | Description |
+|:----- | ---- | ----------- |
+{{#each params}}
+| `{{{name}}}` | `{{{type}}}` | {{{joinLines natspec}}} |
+{{/each}}
+{{#if natspec.returns}}
+| **Output** | |
+{{#each returns}}
+| {{#if name}} `{{name}}` {{else}} `{{@index}}` {{/if}} | `{{type}}` | {{{joinLines natspec}}} |
+{{/each}}
+{{/if}}
+{{else}}
+{{#if natspec.returns}}
+| Output | Type | Description |
+| ------ | ---- | ----------- |
+{{#each returns}}
+| {{#if name}} `{{{name}}}` {{else}} `{{{@index}}}` {{/if}} | `{{type}}` | {{{joinLines natspec}}} |
+{{/each}}
+{{/if}}
+{{/if}}
+
+{{#if natspec.dev}}
+*{{{natspec.dev}}}*
+{{/if}}

contracts/docs/templates/contract.hbs

@@ -0,0 +1,12 @@
+## Description
+
+{{{natspec.notice}}}
+
+{{{natspec.dev}}}
+
+## Implementation
+
+{{#each items}}
+{{>item}}
+{{/each}}
+<!--CONTRACT_END-->

contracts/docs/templates/enum.hbs

@@ -0,0 +1,9 @@
+{{>common}}
+
+```solidity
+enum {{name}} {
+{{#each members}}
+  {{name}}{{#unless @last}},{{/unless}}
+{{/each}}
+}
+```

contracts/docs/templates/error.hbs

@@ -0,0 +1 @@
+{{>common}}

contracts/docs/templates/event.hbs

@@ -0,0 +1 @@
+{{>common}}

contracts/docs/templates/function.hbs

@@ -0,0 +1 @@
+{{>common}}

contracts/docs/templates/helpers.ts

@@ -0,0 +1,66 @@
+import {HelperOptions, Utils} from 'handlebars';
+
+/**
+ * Returns a Markdown heading marker. An optional number increases the heading level.
+ *
+ *    Input                  Output
+ *    {{h}} {{name}}         # Name
+ *    {{h 2}} {{name}}       ## Name
+ */
+export function h(opts: HelperOptions): string;
+export function h(hsublevel: number, opts: HelperOptions): string;
+export function h(hsublevel: number | HelperOptions, opts?: HelperOptions) {
+  const {hlevel} = getHLevel(hsublevel, opts);
+  return new Array(hlevel).fill('#').join('');
+}
+
+/**
+ * Delineates a section where headings should be increased by 1 or a custom number.
+ *
+ *    {{#hsection}}
+ *    {{>partial-with-headings}}
+ *    {{/hsection}}
+ */
+export function hsection(opts: HelperOptions): string;
+export function hsection(hsublevel: number, opts: HelperOptions): string;
+export function hsection(
+  this: unknown,
+  hsublevel: number | HelperOptions,
+  opts?: HelperOptions
+) {
+  let hlevel;
+  ({hlevel, opts} = getHLevel(hsublevel, opts));
+  opts.data = Utils.createFrame(opts?.data);
+  opts.data.hlevel = hlevel;
+  return opts.fn(this as unknown, opts);
+}
+
+/**
+ * Helper for dealing with the optional hsublevel argument.
+ */
+function getHLevel(hsublevel: number | HelperOptions, opts?: HelperOptions) {
+  if (typeof hsublevel === 'number') {
+    hsublevel = Math.max(1, hsublevel);
+  } else {
+    opts = hsublevel;
+    hsublevel = 1;
+  }
+  const contextHLevel: number = opts?.data?.hlevel ?? 0;
+  return {opts, hlevel: contextHLevel + hsublevel};
+}
+
+export function trim(text: string) {
+  if (typeof text === 'string') {
+    return text.trim();
+  }
+}
+
+export function toLowerCase(text: string) {
+  return text.toLowerCase();
+}
+
+export function joinLines(text?: string) {
+  if (typeof text === 'string') {
+    return text.replace(/\n+/g, ' ');
+  }
+}

contracts/docs/templates/modifier.hbs

@@ -0,0 +1 @@
+{{>common}}

contracts/docs/templates/page.hbs

@@ -0,0 +1,7 @@
+
+{{#each items}}
+{{#hsection}}
+{{>item}}
+{{/hsection}}
+
+{{/each}}

contracts/docs/templates/struct.hbs

@@ -0,0 +1,9 @@
+{{>common}}
+
+```solidity
+struct {{name}} {
+{{#each members}}
+  {{{typeName.typeDescriptions.typeString}}} {{name}};
+{{/each}}
+}
+```

contracts/docs/templates/user-defined-value-type.hbs

@@ -0,0 +1 @@
+{{>common}}

contracts/docs/templates/variable.hbs

@@ -0,0 +1 @@
+{{>common}}