{"id":24196554,"url":"https://github.com/dedis/medchain-frontend","last_synced_at":"2025-09-09T23:49:24.116Z","repository":{"id":80490943,"uuid":"362105013","full_name":"dedis/medchain-frontend","owner":"dedis","description":"Frontend for the blockchain-based access control system for medical data.","archived":false,"fork":false,"pushed_at":"2021-11-29T13:45:03.000Z","size":4303,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-03T08:22:38.563Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://medco.epfl.ch","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dedis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-27T12:30:47.000Z","updated_at":"2023-02-25T23:57:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"15e5b3e6-159b-4bf9-a91b-cd9766d2b0d1","html_url":"https://github.com/dedis/medchain-frontend","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dedis/medchain-frontend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fmedchain-frontend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fmedchain-frontend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fmedchain-frontend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fmedchain-frontend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dedis","download_url":"https://codeload.github.com/dedis/medchain-frontend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fmedchain-frontend/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269956171,"owners_count":24503113,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-13T19:35:51.763Z","updated_at":"2025-08-11T21:03:46.570Z","avatar_url":"https://github.com/dedis.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 1. Medchain Administration UI\n\nThe project goal was to create an administration interface for the access control and auditability system [MedChain](https://github.com/ldsec/medchain). \n    \nBy using the administration interface, administrators are able to collectively govern the MedChain ecosystem. They collectively manage the MedChain Administrator Consortium. They decide the set of keys belonging to the consortium and the collective signature policy. They also manage the access rights of the researchers that use the privacy-preserving analysis and sharing system of sensitive medical data MedCo \\cite{medco}.\n    \nThe administration interface developed during this project is operational and can already be deployed in the MedChain ecosystem. Some improvements and iterations will probably be needed in the future to increase performances and user experience. The application is very lightweight and operates at a low level of abstraction with the underlying Byzcoin data store. This will ease the addition of features in the future.\n\n# 2. Table of Content\n\n- [1. Medchain Administration UI](#1-medchain-administration-ui)\n- [2. Table of Content](#2-table-of-content)\n- [3. Setup](#3-setup)\n  - [3.1. Setup a Byzcoin chain](#31-setup-a-byzcoin-chain)\n    - [3.1.1. Install medchain](#311-install-medchain)\n    - [3.1.2. Start the byzcoin chain](#312-start-the-byzcoin-chain)\n  - [3.2. Setup the app](#32-setup-the-app)\n    - [3.2.1. Install all the dependencies](#321-install-all-the-dependencies)\n    - [3.2.2. Add the correct roster file](#322-add-the-correct-roster-file)\n    - [3.2.3. npm run start to start the application](#323-npm-run-start-to-start-the-application)\n    - [3.2.4. Build the project](#324-build-the-project)\n  - [3.3. Cleanup](#33-cleanup)\n    - [3.3.1. Cleanup Bypros](#331-cleanup-bypros)\n    - [3.3.2. Cleanup Byzcoin nodes](#332-cleanup-byzcoin-nodes)\n- [4. Functionalities walkthrough](#4-functionalities-walkthrough)\n  - [4.1. Register user keys](#41-register-user-keys)\n  - [4.2. Administration Panel](#42-administration-panel)\n    - [4.2.1. Add an administrator](#421-add-an-administrator)\n    - [4.2.2. Remove an administrator](#422-remove-an-administrator)\n    - [4.2.3. Modify the multi-signature rule policy](#423-modify-the-multi-signature-rule-policy)\n    - [4.2.4. Modify an administrator identity](#424-modify-an-administrator-identity)\n  - [4.3. Transactions Panel](#43-transactions-panel)\n    - [4.3.1. Sign and execute a transaction](#431-sign-and-execute-a-transaction)\n    - [4.3.2. View the past executed transactions](#432-view-the-past-executed-transactions)\n  - [4.4. Projects Panel](#44-projects-panel)\n    - [4.4.1. Create a new project](#441-create-a-new-project)\n    - [4.4.2. Add a user to a project](#442-add-a-user-to-a-project)\n    - [4.4.3. Add rights to a user](#443-add-rights-to-a-user)\n    - [4.4.4. remove rights from a user](#444-remove-rights-from-a-user)\n- [5. Organization](#5-organization)\n  - [5.1. Classes](#51-classes)\n  - [5.2. Components](#52-components)\n    - [5.2.1. Administration](#521-administration)\n    - [5.2.2. Projects](#522-projects)\n    - [5.2.3. Transactions](#523-transactions)\n    - [5.2.4. Other components](#524-other-components)\n  - [5.3. Services](#53-services)\n  - [5.4. Hooks](#54-hooks)\n  - [5.5. Packages](#55-packages)\n  - [5.6. Limitations](#56-limitations)\n \n# 3. Setup\n\nBelow we detail how you can setup a local roster of nodes running a Byzcoin blockchain. A video recording of the whole setup is available in the medchain [Google Drive](https://drive.google.com/file/d/12SjXxGTMoFNSw3HngJdmxCi6GLSEQNpR/view?usp=sharing).\n\n## 3.1. Setup a Byzcoin chain\n\nWe assume you are in a folder located at `$ROOT`\n\n```\nexport ROOT=${PWD}\n```\n\n### 3.1.1. Install medchain\n\n**You need to have the latest version of the Medchain administration cothority service**\n\n```sh\ncd $ROOT\ngit clone https://github.com/ldsec/medchain.git\n```\n\n-----------\n\n### 3.1.2. Start the byzcoin chain\n\n**Install bcadmin, the byzcoin CLI**\n\nThe Byzcoin CLI allows you to interact with the byzcoin blockchain with a low level of overhead.\n\n```sh\ncd $ROOT\ngit clone https://github.com/dedis/cothority.git\ncd $ROOT/cothority/byzcoin/bcadmin\ngo install\n```\n\n**Start the proxy**\n\nThe Bypros proxy allows you to fetch data from Byzcoin by sending SQL queries to the Bypros proxy server. Still in the Medchain repository you need to lauch the Bypros service by running:\n\n```sh\n# In the medchain repository\ncd $ROOT/medchain/bypros\ndocker-compose up\n```\n\nIf you want to run the docker container in background you can run\n\n```sh\n# In the medchain repository\ncd $ROOT/medchain/bypros\ndocker-compose up -d\n```\n\n**Start the conodes**\n\nThen, when you launch the conode, export the needed variables for the proxy. The proxy needs two URLs to connect to the database: one with read/write, and another one with read-only access. ⚠️ If you opened a new terminal you might need to export again `$ROOT`.\n```sh\n# user/password are set in the dockerfile (root) and the schema (read-only user).\nexport PROXY_DB_URL=postgres://bypros:docker@localhost:5432/bypros\nexport PROXY_DB_URL_RO=postgres://proxy:1234@localhost:5432/bypros\n```\n\n```sh\n# In the medchain repository\ncd $ROOT/medchain/conode\n# it will fail if the PROXY_DB_URL* variables are not set!\ngo build -o conode \u0026\u0026 ./run_nodes.sh -v 3 -d tmp\n```\n\nThis command will setup 3 nodes and save their files in conode/tmp.\n\n**Setup the Byzcoin genesis DARC for Medchain**\n\nOnce the nodes are running, you may want to create a new skipchain, and perform\nbasic operations like updating the DARC. This can be done with\n[bcadmin](https://github.com/dedis/cothority/tree/master/byzcoin/bcadmin), the\nByzcoin CLI.\n\nWe created a script that allow you to setup the Byzcoin DARC to be ready for running the administration interface.\n\nIf you did not already created a new skipchain running\n\n```sh\n# Still in the medchain repository\ncd $ROOT/medchain\nexport BC_CONFIG=$ROOT/medchain/conode/tmp # Tells bcadmin where the config folder is\nbcadmin -c $BC_CONFIG create $BC_CONFIG/public.toml # Create a new skipchain\n```\n\nThe **previous** command will ouput directly the command you need to execute to export the configuration path for the newly created skipchain:\n\n```sh\nexport BC=\"path/to/bc-722eac63e67c60ac4a1fc97905cce835e2ccce13613da626c1216c4510b8bb93.cfg\"\n```\n\nThen you need to export the administrator key in the `BC_ADMIN_ID` environment variable. To know the identity of the administrator run:\n\n```sh\nbcadmin info\n=\u003e\n- Config:\n-- Roster:\n--- tls://localhost:7774\n--- tls://localhost:7772\n--- tls://localhost:7770\n-- ByzCoinID: 3db1f3a8ebba3bc83009ae2daa12455b1d88b2e00b399abd7f101ec9483a6afb\n-- AdminDarc: 08cc267ced3d8d248e351d6f8f33f3962020e082cf01a960da08279b9bb91d60\n-- Identity: ed25519:936603dbfc52ae05513f102b7205b48390a5bd0eda578fcfb523c071157b0f9f\n- BC: /Users/jean/Library/Application Support/bcadmin/data/bc-3db1f3a8ebba3bc83009ae2daa12455b1d88b2e00b399abd7f101ec9483a6afb.cfg\n```\n\nThen export the identity:\n\n```sh\nexport BC_ADMIN_ID=ed25519:936603dbfc52ae05513f102b7205b48390a5bd0eda578fcfb523c071157b0f9f\n```\n\nNow you need to go to the medchain administration ui repository:\n\n```sh\ncd $ROOT\ngit clone https://github.com/ldsec/medchain-frontend.git\n```\n\nOnce done just run the `setup` command of the Makefile:\n\n```sh\n# In the medchain-frontend repository\ncd $ROOT/medchain-frontend\nmake setup\n```\n\nOnce done you have the byzcoin genesis DARC setup to have all the rules needed for the Medchain administration\n\n---------\n\n## 3.2. Setup the app\n\n\nThis project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app), and the typescript template.\n\n### 3.2.1. Install all the dependencies\n\n```sh\ncd $ROOT/medchain-frontend\nnpm install\n```\n\n### 3.2.2. Add the correct roster file\n\nYou first need to update `$ROOT/medchain-frontend/src/services/roster.ts` to the correct roster, which can be found in `$ROOT/medchain/conode/tmp/public.toml` file in the medchain repository (See the [instructions above](#312-start-the-byzcoin-chain)).\n\nYou also want to copy the ID of the genesis DARC and the ByzcoinID into the `$ROOT/medchain-frontend/src/services/roster.ts` file. \n\n```sh\nbcadmin info\n=\u003e\n- Config:\n-- Roster:\n--- tls://localhost:7774\n--- tls://localhost:7772\n--- tls://localhost:7770\n-- ByzCoinID: 3db1f3a8ebba3bc83009ae2daa12455b1d88b2e00b399abd7f101ec9483a6afb\n-- AdminDarc: 08cc267ced3d8d248e351d6f8f33f3962020e082cf01a960da08279b9bb91d60\n-- Identity: ed25519:936603dbfc52ae05513f102b7205b48390a5bd0eda578fcfb523c071157b0f9f\n- BC: path/to/.../bcadmin/data/bc-3db1f3a8ebba3bc83009ae2daa12455b1d88b2e00b399abd7f101ec9483a6afb.cfg\n```\n\n### 3.2.3. npm run start to start the application\n\n```sh\ncd $ROOT/medchain-frontend\nnpm run start\n```\n\nOnce you started the project, you need to register the public and private key in order to interact with the chain. You need to click on the connect button of the app and register the keys.\n\nYou find the keys by using `bcadmin`. Get the info of Byzcoin first to get the identity of the first administrator generated when configuring the chain:\n\n```sh\nbcadmin info\n=\u003e\n- Config:\n-- Roster:\n--- tls://localhost:7774\n--- tls://localhost:7772\n--- tls://localhost:7770\n-- ByzCoinID: 3db1f3a8ebba3bc83009ae2daa12455b1d88b2e00b399abd7f101ec9483a6afb\n-- AdminDarc: 08cc267ced3d8d248e351d6f8f33f3962020e082cf01a960da08279b9bb91d60\n-- Identity: ed25519:936603dbfc52ae05513f102b7205b48390a5bd0eda578fcfb523c071157b0f9f\n- BC: path/to/.../bcadmin/data/bc-3db1f3a8ebba3bc83009ae2daa12455b1d88b2e00b399abd7f101ec9483a6afb.cfg\n```\n\nAnd then get the public and private key pair\n\n```sh\nbcadmin key -print $BC_CONFIG/key-ed25519:936603dbfc52ae05513f102b7205b48390a5bd0eda578fcfb523c071157b0f9f.cfg\nPrivate: ec553855272bb591cf1d32753baf44cbac75ec57513a771537aad157c2088706\nPublic: 936603dbfc52ae05513f102b7205b48390a5bd0eda578fcfb523c071157b0f9f\n```\n\nThen you need to ask Bypros to follow the Byzcoin roster (for the queries to run). You only need to do it once for every restart of the bypros docker containers.\n\n![Follow Byzcoin Proxy](screens/follow-proxy.png)\n\n\n### 3.2.4. Build the project\n\nBuilds the app for production to the `build` folder.\\\nIt correctly bundles React in production mode and optimizes the build for the best performance.\n\n\n```sh\ncd $ROOT/medchain-frontend\nnpm run build\n```\n\n## 3.3. Cleanup\n\nThis section explains how to cleanup all the generated files.\n\n### 3.3.1. Cleanup Bypros\n\n```sh\n# In the medchain repository\ncd $ROOT/medchain/bypros\ndocker-compose down\nrm -rf postgres/*\n```\n\n### 3.3.2. Cleanup Byzcoin nodes\n\n```sh\n# In the medchain repository\ncd $ROOT/medchain/conode\nrm -rf tmp/*\n```\n\n# 4. Functionalities walkthrough\n\n## 4.1. Register user keys\n\nWhen you first log into the application, you need to register your public and private key pair in order to sign transactions and interact with Byzcoin.\n\n![Register user keys](screens/keys.png)\n\n## 4.2. Administration Panel\n\nThe administration panel is the page where administrator come to manage the administrator consortium.\n\n![Administration Panewl](screens/administration.png)\n\n### 4.2.1. Add an administrator\n\nAdministrators can register a new administrator in the administrator consortium.\n\n![Add an administrator](screens/administration-add.png)\n\n### 4.2.2. Remove an administrator\n\nAdministrators can remove an administrator identity.\n\n![Remove an administrator](screens/administration-remove.png)\n\n### 4.2.3. Modify the multi-signature rule policy\n\nAdministrators can modify the multisignature rule that transactions need to comply with in order for them to be executed.\n\n![Modify multi signature rule](screens/administration-multisig.png)\n\n### 4.2.4. Modify an administrator identity\n\nAdministrators can also modify another administrator identity (ex: if the administrator lost access to his keys).\n\n![Modify identity](screens/administration-edit.png)\n\n## 4.3. Transactions Panel\n\nAdministrators come to the transactions panel to sign and execute all pending deferred transactions\n\n![Transactions panel](screens/transactions.png)\n\n### 4.3.1. Sign and execute a transaction\n\n![Transactions sign and execute](screens/signExecute.png)\n\n### 4.3.2. View the past executed transactions\n\nIn the history panel they can have a view of past executed transactions. They use that panel for audit purposes.\n\n![Transaction History](screens/transactions-history.png)\n\n## 4.4. Projects Panel\n\nThe projects panel is the page where the administrators manage the different dataset access rights. \n\n![Projects panel](screens/projects.png)\n\n### 4.4.1. Create a new project \n\nThey can create a new project.\n\n![Add a new porject](screens/projects-add.png)\n\n### 4.4.2. Add a user to a project\n\nThey can add user to a project and give them access rights.\n\n![Add user to project](screens/projects-add-user.png)\n\n### 4.4.3. Add rights to a user\n\nThey can also add other access rights to an existing user.\n\n![Add right to user](screens/project-add-rights.png)\n\n### 4.4.4. remove rights from a user\n\nThey can also revoke the access rights of a user for a specific project.\n\n![Remove rights from user](screens/project-remove-rights.png)\n\n# 5. Organization\n\n## 5.1. Classes\n\n`classes.ts` export an object that defines CSS classes, for reusability of certain classes accross multiple components.\n\n## 5.2. Components\n\n### 5.2.1. Administration\n\nContains all the components of the Administration page\n\n### 5.2.2. Projects\n\nContains all the components of the Projects page\n\n### 5.2.3. Transactions\n\nContains all the components of the Transactions page\n\n### 5.2.4. Other components\n\n- `Buttons.tsx` defines the buttons of the application\n- `ConnectModal.tsx` defines the modal for the connection (register of the public and private key pair)\n- `Error.tsx` defines the error message component\n- `PageLayout.tsx` is an outer order component that defines the wireframe for any page of the application\n- `Pager.tsx` defines the pagination for the transactions page\n- `PanelElement` defines a section of a box in the UI\n- `Success.tsx` defines the success message component\n\n## 5.3. Services\n\nContains all the different services used to communicate and manipulate the data of the app.\n\n- `byprosQueries.ts` contains Bypros sql queries definitions\n- `CothorityGateway.tsx` contains methods to communicate with Byzcoin.\n- `CothorityTypes.ts` defines certain types used to wrap Cothority objects and used in the application\n- `cothorityUtils.ts` contains helper methods for the different services.\n- `instructionBuilder.ts` contains methods that prepare transaction for the `CothorityGateway.tsx`\n- `messages.ts` contains protobuf to Typescript message definition. These messages are used to unmarshall data from Byzcoin.\n- `roster.ts` contains all the connection details about the roster of conodes and the configuration of Byzcoin.\n\n## 5.4. Hooks\n\n`useLocalStorage.tsx` this hook is used by the `ConnectionContext` to store the public adn private key pair in the local storage of the web browser. \n\u003e Note that this is a limitation. [see below](#limitations)\n  \n## 5.5. Packages\n\n- [**TailwindCSS**](https://tailwindcss.com/): The CSS framework used for creating the styling of the project. The file `tailwind.config.js` is used to personalized the framework to add special styling and extend existing styles.\n  \u003e The documentation is incredible, you search anything in the search bar and you have all the different classes that you can use.\n- [**React Tables**](https://react-table.tanstack.com/): Create tables with add-on functionalities like sorting, filtering...\n- [**classnames**](https://www.npmjs.com/package/classnames) This package is usefull to separate the logic of the different classes you import. \n- [**@dedis/cothority**](https://www.npmjs.com/package/@dedis/cothority) package that provides methods used to communicate with Byzcoin\n- [**React Icons**](https://react-icons.github.io/react-icons) used to import icons in the application. This package is just a repository of most of the famous SVG libraries. You just import the icon in the component and during the build of the project for production it will include the SVG in the final build.\n\n## 5.6. Limitations\n\nNote that this is a limitation. For production environment, this setup provide no security if the private key. A solution would be to encrypt the private key and store the ciphertext in a JSON file. And decrypt at runtime asking for the password of the administrator.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdedis%2Fmedchain-frontend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdedis%2Fmedchain-frontend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdedis%2Fmedchain-frontend/lists"}