KappaSigmaMu App

This is a dedicated interface for Kusama Society.

Dependencies

• Node v24.18.0
• yarn

Setup

• Clone this repository.

• Copy the development sample config file on the root folder:

cp .env.development.sample .env.development

Use "PROVIDER_SOCKET": "wss://kusama-rpc.polkadot.io" (or one of the other options available on the sample config file) if you want to connect to production RPC

Installation

yarn install

Running with Docker

• Run:

docker-compose up

• Open http://localhost:3000 to view it in the browser. The container share the sources files with your machine. The application compiles automatically after editing.

Running a development node of Kusama

Using Chopsticks:

• Copy the development sample config file on the config folder:

cp config/kusama.yml.sample config/kusama.yml

• Use Chopsticks and set "PROVIDER_SOCKET": "ws://127.0.0.1:8000" on your .env.development to run a local fork of Kusama with predetermined Society storage and a custom runtime (uncomment the wasm-override parameter on the config file if you want a custom runtime):

yarn chopsticks

• Private keys for development accounts. Change hard derivation key to switch from Alice to Bob, Charlie, etc. Use this private key to import these development accounts to a wallet of your choice.

bottom drive obey lake curtain smoke basket hold race lonely fit walk//Alice

Building and running your own custom runtime

Chopsticks allows for custom runtimes to be used. You can build a custom runtime using our fork of the runtimes repository, this version changes the rotation periods from days to seconds, in order to facilitate tests and development.

• Follow this guide to install Rust and the necessary dependencies to build Substrate
• Clone the forked repository and checkout to this branch:

git checkout customized-society-pallet

• Change the code (if you need, if not you can skip this step and use our customized version)
• In the root folder of the forked repository, browse to Kusama's runtime directory

cd relay/kusama

• Inside the directory, run:

cargo build --release

• After finishing the build, browse back to the root directory and copy the wasm blob to this repository, renaming it to custom-kusama-runtime.wasm:

cp target/release/wbuild/staging-kusama-runtime/staging_kusama_runtime.wasm ../kappasigmamu.github.io/custom-kusama-runtime.wasm

• Uncomment the wasm-override parameter on config/kusama.yml and run Chopsticks:

yarn chopsticks

• You can also access Polkadotjs pointing to your development node to interact with it.

Managing Proof-of-Ink images

We use IPFS to host the images and Pinata to pin the folder. The images are optimized and renamed to <member_hash>.jpg before getting uploaded. The scripts can be found inside scripts/poi.

Requirements:

• Python libraries:

pip3 install Pillow pillow-heif python-dotenv

Optimizing images

• Optimize an entire folder:

python3 optimize_multiple.py <folder_path>

• Rename and optimize single image:

python3 rename_and_optimize.py <image_path> <member_hash>

Interacting with IPFS/Pinata

• PS: requires a .env inside scripts/poi with PINATA_API_KEY and PINATA_API_SECRET
• Install IPFS and run it:

ipfs daemon

• Upload folder to Pinata and pin it:

python3 upload.py <file_path>

• Download pinned folder:

python3 download.py <ipfs_hash> <download_path>

• Full job - takes a new image, renames and optimizes it, uploads the new folder to Pinata and pins it, and finally unpins the old folder. The optional param force let's you overwrite an image that already exists.

python3 job.py <image_path> <member_hash> [optional=force]

Application:

yarn start

Linter

yarn lint

You can automatically fix some issues with yarn lint:fix

Tests

Unit tests (Jest)

yarn test

Launches Jest in interactive watch mode.

Non-watch run (as used in CI):

CI=true yarn test --watchAll=false

End-to-end tests (Cypress)

E2E tests run against a local Chopsticks fork and the test dev server. Copy the Chopsticks config first:

cp config/kusama.yml.sample config/kusama.yml

Run a suite:

yarn test:e2e:smoke
yarn test:e2e:wallet
yarn test:e2e:bidding
yarn test:e2e:payouts
yarn test:e2e:candidate-voting
yarn test:e2e:members
yarn test:e2e:membership-claim
yarn test:e2e:user-journeys
yarn test:e2e:error-handling
yarn test:e2e:suspended

Run every suite:

yarn test:e2e        # alias for test:e2e:all
yarn test:e2e:all

Run tests matching a title substring:

yarn test:e2e:grep "should place a bid"

Re-run only tests that failed in the previous run (any command above accepts this flag):

yarn test:e2e:bidding --failed
yarn test:e2e:all --failed
yarn test:e2e:grep "place a bid" --failed

Failed tests are cached in cypress/.cache/failed-tests.json after each run.

Interactive / local debugging:

yarn test:e2e:open     # Cypress UI with Chopsticks + dev server
yarn test:e2e:headed   # headless runner with visible browser (no servers started)

All suite commands are implemented by scripts/test-e2e.js, which starts Chopsticks, waits for RPC readiness, starts the app, and runs Cypress.

Production bundle

yarn build

Builds the app for production to the build folder.

Documentation

• Substrate Developer Hub
• Create React App
• Polkadot js API
• Chopsticks