Skip to content

Commit

Permalink
Merge pull request #5 from Cybersecurity-LINKS/docs-mediterraneus
Browse files Browse the repository at this point in the history
Update mediterraneus docs
  • Loading branch information
lucagiorgino committed Mar 13, 2024
2 parents 1e7fb70 + 9c29e78 commit e3f18a2
Show file tree
Hide file tree
Showing 9 changed files with 321 additions and 27 deletions.
14 changes: 0 additions & 14 deletions docs_mediterraneus/running-the-protocol.md

This file was deleted.

8 changes: 8 additions & 0 deletions docs_mediterraneus/running-the-protocol/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"label": "Running the protocol",
"position": 2,
"link": {
"type": "generated-index",
"description": "Github repositories of the Mediterraneus protocol, follow the instructions to deploy the demo."
}
}
32 changes: 32 additions & 0 deletions docs_mediterraneus/running-the-protocol/connector-rs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
sidebar_position: 3
---

# Connector

- [**mediterraneus-connector-rs**](https://github.com/Cybersecurity-LINKS/mediterraneus-connector-rs), the connector handles user identity and assets,

## Requirements

## Prepare environment

0. Generate contract bindings (to be done once or if contract change)
```sh
# assuming the mediterraneus-smart-contracts folder is located in the same root folder of mediterraneus-connector-rs
cd abigen
cargo run -- --contract ERC721Base --abi-source "../../mediterraneus-smart-contracts/artifacts/contracts/ERC721Base.sol/ERC721Base.json"
```
1. In `connector-rs/env` folder, create a `.env` file starting from `.env.example` and update the values accordingly to your development enviroment.

## Running the Application

1. Launch [IPFS desktop](https://docs.ipfs.tech/install/ipfs-desktop/) and start up the database by running:
```sh
cd connector-rs
docker compose up -d
```
2. Run the connector service:
```sh
cd connector-rs
cargo run --release -- --rpc-provider "http://127.0.0.1:8545/" --chain-id 31337
```
73 changes: 73 additions & 0 deletions docs_mediterraneus/running-the-protocol/frontend-demo.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
sidebar_position: 4
---

# Frontend

- [**mediterraneus-frontend**](https://github.com/Cybersecurity-LINKS/mediterraneus-frontend), sample frontend application for interacting with the connector, issuer, and catalogue.

# Running the Application

To run the frontend application, follow these steps:

1. Install the dependencies by running `npm install`.

2. Copy the `.env.example` file and rename it to `.env`. Make any necessary modifications to the `.env` file.

3. Copy both the `addresses` and `artifact` folders from the [`mediterraneus-smart-contracts`](https://github.com/Cybersecurity-LINKS/mediterraneus-smart-contracts) repository (these folders are obtained after deploying the smart contracts) into the `src` folder of the frontend application.

4. Finally, execute the application by running `npm run dev`.

## IOTA Identity Framework
The identity bindings include all the modules needed for creating and managing a Self-Sovereign Identity.
This results in having also the **iota-client** dependency, that is automatically included in the bindings itself.

### Install the bindings
In order to use the identity framework we have to install the dependency using npm

```sh
npm install @iota/identity-wasm
```
To use this in a web application we have enable the library. The loads the WASM file with an HTTP GET request, so the .wasm file must be copied to the root of the dist folder.

1. Install rollup-plugin-copy:

```sh
npm install rollup-plugin-copy --save-dev
```

2. Add the copy plugin usage to the plugins array under vite.config.ts:
```ts
plugins: [react(), tsconfigPaths(),
// Add the copy plugin to the `plugins` array of your rollup config:
copy({
targets: [
{
src: "node_modules/@iota/sdk-wasm/web/wasm/iota_sdk_wasm_bg.wasm",
dest: "public/libraries",
rename: "iota_sdk_wasm_bg.wasm",
},
{
src: "node_modules/@iota/identity-wasm/web/identity_wasm_bg.wasm",
dest: "public/libraries",
rename: "identity_wasm_bg.wasm",
},
],
})
],
...
```

The .wasm files will be downloaded and stored in the /public/libraries folder.

3. At this stage, the identity and the sdk .wasm files have to be loaded:
```ts
import init from "@iota/sdk-wasm/web";
import * as identity from "@iota/identity-wasm/web";

// Calling identity.init().then(<callback>) or await identity.init() is required to load the Wasm file from the server if not available,
// because of that it will only be slow for the first time.

init("sdk_wasm_bg.wasm") // fix with the right path
.then(() => identity.init("identity_wasm_bg.wasm")); // fix with the right path
```
62 changes: 62 additions & 0 deletions docs_mediterraneus/running-the-protocol/issuer-rs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
---
sidebar_position: 2
---

# Issuer

- [**mediterraneus-issuer-rs**](https://github.com/Cybersecurity-LINKS/mediterraneus-issuer-rs), Issuer of verifiable credentials using smart contracts to bind Externally Owned Accounts (EOAs) with Self-Sovereign Identities (SSI). Sample implementation for the Mediterraneus Protocol,

## Requirements
1. [cargo](https://www.rust-lang.org/learn/get-started), with `rustc 1.74 or newer`
2. [docker](https://docs.docker.com/get-docker/)

## Prepare environment

1. Create a `.env` file starting from `.env.example` and update the values accordingly to your development enviroment.

```conf
PRIVATE_KEY='<issuer private key>'
NON_SECURE_MNEMONIC='<iota wallet mnemonic>'
KEY_STORAGE_MNEMONIC='<identity key storage mnemonic>'
IDENTITY_SC_ADDRESS='<address of the Identity smart contract>'
```

Optional:
- Update the `abi/idsc_abi.json` file if there are changes to the Identity Smart Contract.

## Running the Application

1. Start up the database by running:
```
docker compose up -d
```

2. Run the issuer service
```sh
# For local node Provider
cargo run --release -- -l

# For Shimmer Provider
cargo run --release

# For custom Provider (example Sepolia)
cargo run --release -- --custom-node https://sepolia.infura.io/v3/<API_KEY> --chain-id 11155111
```

Keep in mind that when using the local node setup, the Identity ABI needs to be manually copied into the `abi` folder. Additionally, ensure that the file is named `idsc_abi.json`. On the other hand, when working with a public network, consider publishing the ABI and dynamically loading it through an API.

<!--
## Issuer initialization
The issuer must posses an SSI comprising of at least a DID. At application start up the issuer creates a new identity or retrieves it from the local database.
This is an insecure implementation due to the clear-text storage of the sensitive information of its identity. This must be solved with the usage of secure storage solutions like Stronghold.
## Verifiable Credential Issuance
Before issuing a VC the Issuer must perform the following operations:
1. Resolve the requester's DID and retrieve the verification method public key.
## Useful links
- [Actix postgres example](https://github.com/actix/examples/blob/master/databases/postgres/src/main.rs)
- [ethers-rs](https://docs.rs/ethers/latest/ethers/contract/struct.ContractInstance.html)
-->
130 changes: 130 additions & 0 deletions docs_mediterraneus/running-the-protocol/smart-contracts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
---
sidebar_position: 1
---

# Smart contracts

- [**mediterraneus-smart-contracts**](https://github.com/Cybersecurity-LINKS/mediterraneus-smart-contracts), smart contracts for the Mediterraneus protocol,

## Requirements
1. [Solidity compiler (hardhat)](https://hardhat.org/)
2. [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)

## Prepare environment

1. Create a `.env` file starting from `.env.example` file and update the values accordingly.

```conf
PRIVATE_KEY_ISSUER='<priv_key>'
```

2. In the `hardhat.config.js` specify the various networks to play around with different accounts.

```js
'hardhat-issuer': {
url: 'http://127.0.0.1:8545/',
chainId: 31337,
gas: 2100000,
gasPrice: 8000000000,
accounts: [process.env.PRIVATE_KEY_ISSUER],
},
```

## Local Deployment
Smart contracts can be deployed on the hardhat local network. It is an EVM-like emulated chain.

1. Clone the repository and install the dependecies.
```sh
npm install --save-dev
```

2. Compile the contracts
```sh
npx hardhat compile
```

3. Start a local node
```sh
npx hardhat node
```

4. To fund issuer and other addresses
```sh
npx hardhat --network localhost faucet <eth-address>
```

5. In other shell we can run the deploy script by specifying the local hardhat network
```sh
npx hardhat run --network hardhat-issuer scripts/deploy.js
```


## Run the scripts

1. Deploy the contracts
```sh
npx hardhat run --network shimmerevm-testnet scripts/deploy.js
```

2. Run the various scripts to play with the contracts
```sh
npx hardhat run --network <your-network> scripts/<script.js>
```

## Verify the deployed smart contracts code
Verifying a contract means making its source code public, along with the compiler settings you used, which
allows anyone to compile it and compare the generated bytecode with the one that is deployed on-chain.

1. Modify the hardhat config by adding the `etherscan` information as follows:
```js
module.exports = {
solidity: "0.8.18",
settings: {
...
},
networks: {
...
},
etherscan: {
apiKey: {
'shimmerevm-testnet': 'ABCDE12345ABCDE12345ABCDE123456789'
},
customChains: [
{
network: 'shimmerevm-testnet',
chainId: 1071,
urls: {
apiURL: 'https://explorer.evm.testnet.shimmer.network/api',
browserURL: 'https://explorer.evm.testnet.shimmer.network/'
}
}
]
}
};
```

2. Verify the SCs' code:
```sh
npx hardhat verify --network shimmerevm-testnet <contract address> "<contract constructor Arg1>" "<contract constructor Arg2>"
```

<!-- ## Smart Contracts literature used for developement
1. Writing Upgradeable SCs
```
https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable
https://docs.openzeppelin.com/contracts/4.x/upgradeable
Proxy Smart Contracts
https://docs.openzeppelin.com/contracts/4.x/api/proxy
```
2. Support for EIP-2612
```
https://eips.ethereum.org/EIPS/eip-2612
https://soliditydeveloper.com/erc20-permit
```
3. Timestamp manipulation (the 15 seconds rule)
```
https://consensys.github.io/smart-contract-best-practices/development-recommendations/solidity-specific/timestamp-dependence/
``` -->
Loading

0 comments on commit e3f18a2

Please sign in to comment.