Table of Contents:
- Overview ๐
- Getting started ๐
- Customization ๐จ
- The Stack ๐ฅ
- Live Examples ๐
- Deployment ๐ข
- VSCode Setup ๐
- FAQs & Troubleshooting ๐ฌ
Decentralized Remote Work Platform for Refugees on Web3 and Polkadot
The Decentralized Remote Work Platform for Refugees is a pioneering application operating within the Web3 framework and leveraging the Polkadot network. This platform addresses the hurdles faced by refugees in securing remote work opportunities and integrating into the workforce through a decentralized, transparent, and secure solution.
Key Features:
-
User Registration and Profile Management: Individuals including refugees, employers, government entities, and platform administrators can register and maintain their profiles, supplying requisite information for identity verification and matching purposes.
-
Government Refugee Status Confirmation: Government agencies are empowered to confirm the refugee status of individuals, ensuring verified refugees have access to platform services.
-
Refugee Profile and Live Resume Creation: Refugees are enabled to create dynamic profiles and resumes, securely stored on the IPFS (InterPlanetary File System) to ensure data integrity and accessibility.
-
Employer Registration and Verification: Employers can register on the platform, providing essential company information for verification by platform administrators, thus ensuring the legitimacy of job postings.
-
Employment Contract Creation and Matching: Employers can craft job listings with comprehensive descriptions, including positions, keywords, pay rates, hours, and conditions. Advanced matching algorithms connect refugees with suitable job opportunities based on their profiles and preferences.
Benefits of Web3 and Polkadot Integration:
-
Decentralization and Transparency: Web3 technologies eliminate intermediaries, providing transparency in job matching, payments, and reviews.
-
Data Integrity and Security: IPFS data storage and Polkadot's security features ensure the integrity and security of user data, safeguarding sensitive information like personal identification and employment documents.
-
Interoperability and Scalability: Integration with Polkadot facilitates seamless communication and data exchange with external systems like government databases and financial services. Scalability ensures the platform accommodates a growing user base without compromising performance.
-
Community Governance: Built on a decentralized network, the platform allows stakeholders to participate in decision-making and contribute to its development and evolution.
-
Cross-Chain Compatibility: Polkadot's interoperability extends to other blockchains, enabling interaction with different ecosystems for accessing a broader range of services and resources.
The Decentralized Remote Work Platform for Refugees revolutionizes refugee access to remote job opportunities, ensuring transparency, security, and inclusivity while leveraging the benefits of decentralization and blockchain technology.
-
Account: 4CfR5Gw8L1n4tgMr2Ud31vyrRzUBUdSGCwDjCJ8AJAkLLFYA
-
Smart Contract Address: 5GSZpLBykXuVFZ5nK8brrE1nNhyn8UozU3tqkng7NzhY7arV
-
On Aleph Zero Testnet (https://contracts-ui.substrate.io/contract/5GSZpLBykXuVFZ5nK8brrE1nNhyn8UozU3tqkng7NzhY7arV)
The frontend works out of the box, without a local node running, as the sample contract is pre-deployed on certain live testnets (i.e. alephzero-testnet
). Necessary deployment metadata and addresses are provided under contracts/deployments/
.
Pre-requisites:
- Setup Node.js v18+ (recommended via nvm with
nvm install 18
)- Install pnpm (recommended via Node.js Corepack or
npm i -g pnpm
)- Clone this repository
Special Instructions for Windows Users
[!IMPORTANT]
Windows users must either use WSL (recommended) or a custom shell like Git Bash. PowerShell is not supported.
Pre-requisites when using WSL for Linux:
- Install WSL and execute all commands in the WSL terminal
- Setup Node.js v18+ (recommended via nvm with
nvm install 18
)- Install the following npm packages globally:
npm i -g npm
npm i -g pnpm node-gyp make
- Clone this repository into the WSL file system (e.g.
/home/<user>/inkathon
).Tip: You can enter
\\wsl$\
in the top bar of the Windows Explorer to access the WSL file system visually.
# Install dependencies (once)
# NOTE: This automatically creates an `.env.local` file
pnpm install
# Start Next.js frontend
pnpm run dev
Optionally, to enable simple-git-hooks
(for automatic linting & formatting when committing), you can run the following command once: pnpm simple-git-hooks
.
The contracts/package.json
file contains shorthand scripts for building, testing, and deploying your contracts. To run these scripts, you need to set contracts/
as the active working directory in your terminal.
Pre-requisites:
- Install Rust via the Substrate Docs (skip the "Compile a Substrate node" section)
- Install
cargo contract
- Install
substrate-contracts-node
# Build contracts and move artifacts to `contracts/deployments/{contract}/` folders
pnpm run build
# Start local node with persistence (contracts stay deployed after restart)
# NOTE: When using Brave, shields have to be taken down for the UIs
pnpm run node
## IMPORTANT: Open a separate terminal window and keep the node running
# Deploy the contracts on the local node
pnpm run deploy
Alternatively, you can also deploy contracts manually using Contracts UI (pnpm contracts-ui
) in the browser.
Open the frontend/.env.local
file and set the NEXT_PUBLIC_DEFAULT_CHAIN
variable to development
. Then restart the frontend and you should be able to interact with the contracts deployed on your local node.
Read more about environment variables and all available chain constants in the Environment Variables section below.
There are multiple places where you need to insert your project's name and identifier. Most of these occurrences are highlighted with a /* TODO */
comment in the code. You can easily replace them one by one by installing the todo-tree
plugin.
Additionally, there are the following un-highlighted occurrences:
- the name of the
inkathon.code-workspace
file - the
package.json
's name & metadata in the root directory as well as in thecontracts/
andfrontend/
packages - the workspace dependency (
@inkathon/contracts
) defined infrontend/package.json
and imported infrontend/src/deployments/deployments.ts
To replace the default Greeter
contract or add a new one, you need to do the following:
- Add a new contract directory under
contracts/src/
- Add it as another workspace member to the
contracts/Cargo.toml
file - Add another deployment script or adjust
contracts/scripts/deploy.ts
- Adjust the
ContractIds
enum andgetDeployments
function infrontend/src/deployments/deployments.ts
Adding custom scripts is useful to interact with your contracts or test certain functionality. Therefore, just duplicate & reuse the contracts/scripts/script.template.ts
file and run it via pnpm run script <script-name>
. This command will run the TypeScript file directly via tsx
.
For general scripts, the same environment variable initialization & configuration applies as described below in the Deployment section (e.g. to change the target network).
Spinning up a deployment via Vercel is pretty straightforward as the necessary settings are already configured in vercel.json
. If you haven't cloned the repository yet, you can also use the Deploy button below to create a new repository from this template.
Alternatively, you can also use the provided Dockerfiles to deploy to any hosting provider of your choice. Read more here.
Below you find live Demo for Zealix
- Zealix โ The Silo of Hope
All environment variables are imported from process.env
in frontend/src/config/environment.ts
and re-exported from there. For improved type safety, Always only import environment variables from @/config/environment
and never directly from process.env
.
Environment Variables | Default Values | Description |
---|---|---|
NEXT_PUBLIC_DEFAULT_CHAIN *๏ธโฃ |
๏ธalephzero-testnet |
The network (Substrate-based chain) the frontend should connect to by default and what contract deployment artifacts to import. |
NEXT_PUBLIC_PRODUCTION_MODE |
false |
Optional boolean flag to differentiate production environment (e.g. for SEO or Analytics). |
NEXT_PUBLIC_URL |
http://localhost:3000 |
Optional string that defines the base URL of the frontend (will be auto-inferred from Vercel environment variables). |
NEXT_PUBLIC_SUPPORTED_CHAINS |
โ | Optional array with network identifers (e.g. ["alephzero-testnet", "shibuya"] ) that are supported by the frontend, if the dApp is supposed to be multi-chain. |
*๏ธโฃ Required
One key element making this boilerplate so flexible is the usage of environment variables to configure the active network in the frontend. This is done by setting the NEXT_PUBLIC_DEFAULT_CHAIN
variable in the frontend/.env.local
file, or in the deployment settings respectively.
If your network is not provided by the use-inkathon
library, you can add it manually by creating a new SubstrateChain
object. If you think a chain is missing, please open an issue or PR.
Important
All supported chain constants can be found here in the scio-labs/use-inkathon
repository.
In the Getting Started section above, we've already deployed the sample Zealix
contract on a local node. To target a live network, we can use the CHAIN
environment variable when running the deploy
script.
CHAIN=alephzero-testnet pnpm run deploy
Further, dynamically loaded environment files with the .env.{chain}
naming convention can be used to add additional configuration about the deployer account.
# .env.alephzero-testnet
ACCOUNT_URI=bottom drive obey lake curtain smoke basket hold race lonely fit walk//Alice
When running the same script again, this deployer account defined there will be used to sign the extrinsic.
Warning
These files are gitignored by default, but you should still be extra cautious when adding sensitive information to them.
It can be helpful to develop in VSCode by opening the workspace file inkathon.code-workspace
instead of just the plain directory. This approach offers multiple advantages, like sections in the file explorer, or shortcut actions to open the terminal in the correct directory.
Consider installin the zoma.vscode-auto-open-workspace
extension to automatically open the workspace file when opening the directory.
Additionally, the VSCode plugins listed below are recommended as they can be very helpful when working with this boilerplate.
All Recommended Plugins
Plugin Name | Description |
---|---|
dbaeumer.vscode-eslint |
Adds ESLint editor support. |
esbenp.prettier-vscode |
Adds Prettier editor support. |
bradlc.vscode-tailwindcss |
Adds tailwindcss editor support. |
rust-lang.rust-analyzer |
Adds Rust language support. |
ink-analyzer.ink-analyzer |
Adds ink! language support. |
tamasfe.even-better-toml |
Adds .toml file support. |
gruntfuggly.todo-tree |
Lists all TODO comments in your workspace. |
wayou.vscode-todo-highlight |
Highlights TODO comments in your workspace. |
mikestead.dotenv |
Adds syntax highlighting for .env files. |
Which package managers are supported? Do I have to use pnpm?
For monorepo workspaces, pnpm is likely the fastest and most reliable choice. When using it though, it's strongly recommended everyone on the team uses it. No installs should be performed nor any other lock files should be committed.
As an alternative, yarn is also supported and can be used for installation. Caveats when using yarn:
- Only the stable version of yarn (currently v3) is supported, not yarn classic (v1).
yarn.lock
files should be committed instead of.pnpm-lock.yaml
files.- The
pnpm
CLI is still used in manypackage.json
scripts, so these would have to be adjusted manually.
[!IMPORTANT]
As npm lacks support for theworkspace
import protocol, it's not compatible with ink!athon.
How to solve `Cannot find module './greeter/development.ts'`?
Sometimes, Next.js doesn't pick up changes (i.e. file creations) in the contracts/deployments/{contract}/
folders correctly. E.g., when you just deployed on a local node for the first time and set the frontend's .env.local
to connect to the development
network.
To fix this, you can delete the build cache at frontend/.next
. This is currently the only solution and will force Next.js to rebuild the project and pick up the new files.
[!NOTE]
To prevent this behavior, thecontracts/package.json
file contains a smallpostinstall
script that creates an emptydevelopment.ts
file if none exists.
How to approach styling?
Currently it offers styling via the following options out of the box:
- shadcn/ui - Re-usable components built using Radix UI and Tailwind CSS.
- Vanilla Tailwind CSS styled styles via
className
and*.module.(s)css
files. - Default (S)CSS styles.
[!INFO]
This boilerplate tries to stay as un-opinonated in regards to styling, which means you can use any styling or component library.
How do type-safe contract interactions work?
With typechain-polkadot
, types for each contract (TypeScript files) are created upon build (via the build
script or build-all.sh
command). You can suppress this behavior by passing --skip-types
.
They are stored under contracts/typed-contracts/
and imported directly from the frontend. Then, via the new useRegisteredTypedContract
hook from useInkathon
instances with pre-defined api, network-dependant contract address, and injected signer are being created. See greeter-contract-interactions.tsx
for an example.