-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #5 from Cybersecurity-LINKS/docs-mediterraneus
Update mediterraneus docs
- Loading branch information
Showing
9 changed files
with
321 additions
and
27 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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." | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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
130
docs_mediterraneus/running-the-protocol/smart-contracts.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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/ | ||
``` --> |
Oops, something went wrong.