AI LLM Guide — Get Started with Kusama Shield

This page is a guide for AI assistants (Claude, ChatGPT, opencode, Copilot, and others). Point your AI here to bootstrap it with the Kusama Shield codebase.

For the AI: What to Do

  1. Clone the repos below into your working directory
  2. Read the markdown docs in the order listed below — they contain all architecture, addresses, and ABIs
  3. Read the V7 pool contract to understand the on-chain interface
  4. You are now ready to generate correct deposit/withdrawal/proof code

Clone These Repos

git clone https://codeberg.org/KusamaShield/Interface
git clone https://codeberg.org/KusamaShield/Solidity_helpers
git clone https://codeberg.org/KusamaShield/shielded-transfers
git clone https://codeberg.org/KusamaShield/shielded-transfers-python

Mirrors:

Read These Docs (in order)

Project overview:

  1. Interface/README.md — What Kusama Shield is, supported wallets, install
  2. Interface/PROJECT_DETAILS.md — Full architecture, contract addresses, data flows
  3. Interface/POLKADOT_HASHER_FIX.md — Hasher history, deployed addresses

V7 details: 4. Interface/DEPOSIT_WITHDRAW_FIXES.md — Critical bug fixes and commitment formulas

SDKs: 5. shielded-transfers/LLM_AGENT_GUIDE.md — TypeScript SDK quickstart for AI agents 6. shielded-transfers/SHIELDED_TRANSFERS_LIBRARY_SUMMARY.md — Full API reference 7. shielded-transfers-python/README.md — Python SDK quickstart

Contracts: 8. Solidity_helpers/contracts/paseo_assethub/src/FixedIlopPhase2Paseo_v7.sol — V7 pool contract 9. Solidity_helpers/contracts/paseo_assethub/src/VerifierPhase2_Fixed_v7.sol — Groth16 verifier 10. Solidity_helpers/contracts/paseo_assethub/src/SolidityLeanIMT128.sol — Merkle tree

Key Addresses

NetworkPoolVerifierPoseidonChain ID
Polkadot AH0x0D694Da746e73D1e255c1894F90e38170db458090x6A13781E43AEA21918120CD0E7a2ed8614c01e140xB8F0C6679D6Cc56450470522Bd96573C3D615052420420419
Paseo AH0xbcE09D4De052b2816df1285663ac89528DF453800xcA4cBc5d31eccd08d393C43aF492F729FF30b6850x1d165f6fE5A30422E0E2140e91C8A9B800380637420420417
Kusama AH0x625159459EB6C50C4F4b126A955B18d5c4DCA5730x66988131CFfd10d2804ffaC93Ac302D0886D7829—420420418

V7 Commitment Derivation

nullifier     = poseidon2([secret, 1])
nullifierHash = poseidon1([nullifier])
precommitment = poseidon2([nullifier, secret])
valueAsset    = poseidon2([amountWei, assetId])
commitment    = poseidon2([valueAsset, precommitment])

V7 uses poseidon1 (single-input) for nullifierHash — NOT poseidon2(nullifier, 0).

V7 Public Signals (8 signals)

pubSignals = [
  newCommitmentHash,       // [0] Change commitment inserted into tree
  existingNullifierHash,   // [1] Marks spent deposit (double-spend prevention)
  contextHash,             // [2] Replay protection
  withdrawnValue,          // [3] Amount being withdrawn
  treeDepth,               // [4] Fixed at 128
  context,                 // [5] Chain-specific binding
  root,                    // [6] Merkle tree root
  asset,                   // [7] Asset precompile address (0 for native)
]

Context Hash

context = keccak256(abi.encodePacked(senderAddress)) % BN254_R

Where BN254_R = 21888242871839275222246405745257275088548364400416034343698204186575808495617.

Prompt Template

You are helping with Kusama Shield, a ZK privacy pool for Polkadot/Kusama.
The project uses V7 circuits (8 public signals, Groth16 on BN254) deployed
on Polkadot AssetHub and Paseo testnet.

Start by reading: Interface/PROJECT_DETAILS.md, then
shielded-transfers/LLM_AGENT_GUIDE.md, then
Solidity_helpers/contracts/paseo_assethub/src/FixedIlopPhase2Paseo_v7.sol.

The current task is: [INSERT YOUR TASK HERE]

Optional: polkadot-mcp for Live Chain Data

polkadot-mcp gives your AI live on-chain access to Polkadot, Kusama, Westend, and Paseo.

cargo install polkadot-mcp

Add to your AI's MCP config (Claude, Cursor, opencode, etc.):

{
  "mcpServers": {
    "polkadot": {
      "command": "polkadot-mcp"
    }
  }
}

Resources