IDCHAIN - A Decentralized Identifier Blockchain Infrastructure

Repository Notice This is a public fork of IDCHAIN Gitlab (private). To comply with licensing and confidentiality requirements, this fork contains a limited, sanitized subset of the source code and history. Some features are intentionally omitted or replaced with placeholders.

Overview

IDCHAIN is a blockchain infrastructure built with Mandala Application Chain technology, designed as a Layer-1 solution for decentralized identity and digital credentials. As part of the broader digital identity ecosystem, IDCHAIN provides a secure, scalable, and interoperable platform that enables individuals and organizations to manage their digital identities with full sovereignty and privacy.

Key Features

🔐 Decentralized Identity Management

• Self-sovereign identity (SSI) principles with user-controlled data
• W3C-compliant Decentralized Identifiers (DIDs) standard implementation
• Privacy-preserving identity verification mechanisms
• Cross-chain identity portability and interoperability

📜 Verifiable Credentials System

• Issue, store, and verify digital credentials securely
• Support for multiple credential formats and schemas
• Selective disclosure capabilities for privacy protection
• Tamper-proof credential lifecycle management

Project Components

• Relay Chain Support: Full integration with Polkadot SDK for relay chain validators
• DID System: Decentralized Identifier (DID) capabilities for identity management
• Credentials: Public credential management and verification system
• Delegation: Flexible delegation logic for identity operations
• Asset Switch: Cross-chain asset and identity portability
• Web3 Names: Decentralized naming service for human-readable identities

Use Cases

IDCHAIN enables a wide range of identity-centric applications:

• Digital Identity Wallets: Self-custody identity management
• Educational Credentials: Tamper-proof academic certificates
• Professional Licensing: Verifiable professional qualifications
• Supply Chain Identity: Product authenticity and traceability
• Government Services: Digital citizenship and e-governance
• Healthcare Records: Privacy-preserving medical credentials

For complete project details, technical specifications, and implementation roadmap, refer to the IDCHAIN Whitepaper.

Quick Start

System Requirements

Before starting, ensure your system meets these requirements:

Hardware (Recommended for Production)

• CPU: 8 physical cores @ 3.4GHz (Intel Ice Lake or newer, AMD Zen3 or newer)
• Memory: 32 GB DDR4 ECC
• Storage: 1 TB NVMe SSD
• Network: Minimum 500 Mbit/s symmetric bandwidth
• OS: Linux Kernel 5.16 or newer (Ubuntu 24.04 recommended)

Development Requirements

• Rust 1.74.0 or newer
• Git, Clang, and build essentials
• Optional: Docker for containerized deployment

Prerequisites Setup

Install Rust and Dependencies

sudo apt install --assume-yes git clang curl libssl-dev protobuf-compiler make pkg-config build-essential

curl https://sh.rustup.rs -sSf | sh -s -- -y
source $HOME/.cargo/env

Install specific Rust version:

rustup install 1.74.0
rustup default 1.74.0
cargo --version  # Verify installation

For macOS users:

brew install cmake pkg-config openssl git llvm

Configure NTP (Critical for Network Nodes)

timedatectl  # Check if NTP is synchronized
sudo apt-get install ntp  # If not installed
sudo ntpq -p  # Verify NTP status

Warning: NTP synchronization is critical for block authorship. Nodes with unsynchronized clocks may miss block opportunities.

Verify Landlock is Enabled

sudo dmesg | grep landlock || sudo journalctl -kg landlock

Build the Project

cargo build --release

The build process may take 30-80 minutes depending on your hardware. After completion, verify the installation:

./target/release/did-node --version

Generate Documentation

cargo +nightly doc --open

Running Nodes

Development Mode

Single-Node Development Chain (DID)

./target/release/did-node --dev

To start with detailed logging:

RUST_BACKTRACE=1 ./target/release/did-node -ldebug --dev

To persist state between runs:

mkdir -p ~/my-chain-state
./target/release/did-node --dev --base-path ~/my-chain-state/

To purge the development chain's state:

./target/release/did-node purge-chain --dev

Multi-Node Local Testnet

Refer to Simulate a Network in the Substrate documentation.

Production Deployment

For complete production deployment instructions, refer to the IDCHAIN Relaychain Deployment Handbook, which includes:

• Hardware requirements and benchmarks
• Validator key generation and management
• Chain specification configuration
• Systemd service setup for automated management
• RPC endpoint setup with Nginx for WebSocket access
• Network bootstrapping and monitoring

Quick Start:

git clone https://github.com/MandalaChain/Idchain-pallet.git
cd Idchain-pallet
cargo build --release
./target/release/subkey generate --scheme Sr25519  # Generate validator keys

Parachain Collator Setup

Parachain deployment is now handled through standardized infrastructure. For complete details, refer to the IDCHAIN Parachain Deployment Handbook.

Relay Chain Validator Setup

Complete deployment instructions are available in the IDCHAIN Relaychain Deployment Handbook.

Quick Summary:

1. Build the relay chain binaries from polkadot-sdk
2. Generate validator keys using subkey
3. Create and configure custom chain specification files
4. Configure systemd services for automated management
5. Set up RPC endpoints with Nginx for WebSocket access

Key Steps:

git clone https://github.com/MandalaChain/polkadot-sdk/tree/moonbeam-polkadot-v1.7.2
cd polkadot-sdk
cargo build --release
./target/release/subkey generate --scheme Sr25519  # Generate validator keys

Chain Specifications

A chain specification (chain spec) defines the initial state (genesis) of your blockchain, including network name, boot nodes, validator set, genesis accounts, and runtime parameters.

Chain Spec Files

Chain specifications are available in the chainspecs/ directory:

• Mainnet: chainspecs/parachain-mainnet/parachain-mainnet.json
• Testnet: chainspecs/parachain-testnet/
• Staging: chainspecs/parachain-testnet-stg/
• Standalone: chainspecs/standalone/standalone-testnet.json

Generating Chain Specifications

DID Node

./target/release/did-node build-spec --chain dev > did-dev-spec.json

Raw Format (for production)

./target/release/did-node build-spec --chain=did-dev-spec.json --raw --disable-default-bootnode > did-dev-spec-raw.json

Chain Spec Customization

Modify the JSON chain spec file to:

1. Update name, id, and protocolId fields
2. Configure consensus parameters (aura, grandpa)
3. Set initial validators and their session keys
4. Define genesis balances

For detailed chain spec guidelines, refer to:

• IDCHAIN Relaychain Chainspec Guide

Interacting with the Network

Polkadot.js Apps

Connect to the running node using the Polkadot.js Apps interface:

1. Local Development Node: http://polkadot.js.org/apps/?rpc=ws://127.0.0.1:9944
2. Alternative: IPFS Version

WebSocket RPC Setup

For production nodes, expose the RPC endpoint through Nginx with WebSocket support:

server {
    server_name node-rpc.idchain.id;

    location / {
        proxy_pass http://localhost:9944;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
    }

    listen 80;
}

Then enable SSL:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d node-rpc.idchain.id

Access via: https://polkadot.js.org/apps/?rpc=wss://node-rpc.idchain.id

Project Architecture

Network Structure

IDCHAIN follows a modular architecture designed for scalability and interoperability:

IDCHAIN Ecosystem
├── Relay Chain (Validator Network)
│   ├── Validators (block production & finality)
│   └── Authority Discovery
│

Validator Node

A validator node participates in consensus by:

• Following the consensus mechanism (Aura/BABE for block production, GRANDPA for finality)
• Validating blocks from other network participants
• Maintaining the blockchain state
• Exposing RPC endpoints for external access

Validator Requirements:

• Reference hardware specs (see System Requirements above)
• Synchronized clock (NTP)
• Stable, high-bandwidth internet connection
• Generated validator keys and session keys

Runtime Implementation

The runtime is the core logic of the blockchain responsible for:

• Validating blocks
• Executing state transitions
• Processing extrinsics (transactions)

IDCHAIN uses FRAME to construct the runtime, allowing flexible composition of domain-specific logic through pallets.

Pallets (Runtime Modules)

Custom pallets are located in the pallets/ directory:

Pallet	Purpose
delegation	Delegation logic for governance
pallet-dip-consumer	DIP (Decentralized Identity Provider) consumer pallet
pallet-dip-provider	DIP provider functionality
pallet-did-lookup	DID to address mapping
pallet-web3-names	Web3 name registration and resolution
public-credentials	Credential management and verification
verification	Identity verification mechanisms
uid-core	Universal Identity core functionality
uid-credential	Universal Identity credential management
pallet-asset-switch	Asset switching capabilities
pallet-configuration	Configuration management
pallet-deposit-storage	Deposit and storage management
pallet-migration	Migration utilities
pallet-relay-store	Relay chain state store

Each pallet includes:

• Storage: Key-value data structures for chain state
• Dispatchables: Callable functions (extrinsics) to modify state
• Events: Notifications for state changes
• Errors: Error handling and reporting

Runtime APIs

Located in runtime-api/, these provide read-only access to runtime state:

• asset-switch: Query asset switching functionality
• did: DID lookup and management queries
• dip-provider: DIP provider information and queries
• public-credentials: Credential and verification queries
• staking: Staking information and rewards

Alternative Installations

Nix

Install Nix, and optionally direnv and lorri for a plug-and-play development environment:

direnv allow
lorri shell

Docker

For containerized deployment, refer to Substrate Docker instructions.

Documentation & Resources

Official Handbooks

Comprehensive deployment and configuration guides:

• IDCHAIN Relaychain Deployment Handbook
  • Complete validator node setup guide
  • Hardware requirements and benchmarks
  • Chain specification configuration
  • Systemd service management
  • RPC endpoint setup with Nginx
  • Polkadot.js integration

External Resources

• IDCHAIN Website
• Substrate Documentation
• Polkadot Wiki
• FRAME Developer Guide
• Polkadot JS Apps

Testing & Benchmarking

Running Tests

# Run all tests
cargo test --release

# Run tests for a specific pallet
cargo test -p pallet-dip-consumer --release

Benchmarking

Benchmark your pallets to optimize performance:

cargo build --package frame-benchmarking-cli --release

./target/release/substrate benchmark pallet \
  --chain dev \
  --pallet '*' \
  --extrinsic '*'

Zombienet Testing

For complex network simulations, use Zombienet:

1. Download the Zombienet binary
2. Clone the Polkadot SDK (same branch)
3. Generate plain chain spec:

   ./target/release/idchain-parachain build-spec --disable-default-bootnode --dev > chainspecs/plain-idchain-chainspec.json

4. Configure scripts/zombienet/config.toml and run:

   cd scripts/zombienet
   zombienet -p native spawn config.toml

Common Issues & Troubleshooting

Build Fails

Solution: Ensure Rust version is correct and dependencies are installed:

rustup update
rustup default 1.74.0
rustc --version

Node Won't Start

Solution: Check ports aren't already in use:

lsof -i :9944  # Check RPC port
lsof -i :30333  # Check P2P port

Keys Not Injecting

Solution: Verify the key format and use the correct RPC methods:

curl -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "method": "author_insertKey",
  "params": ["aura", "<seed_phrase>", "<public_key_hex>"],
  "id": 1
}' http://localhost:9944

Performance Issues

Checklist:

• Verify system clock is synchronized (NTP)
• Check network connectivity to peers
• Monitor CPU, memory, and disk I/O
• Increase --wasm-execution optimization if needed
• Consider upgrading hardware

Security

Key Management

⚠️ Critical Security Practices:

• Never share your seed phrases or secret keys
• Store sudo keys in a secure, offline location
• Use hardware wallets for production validator keys
• Rotate keys periodically
• Use environment variables or secure vaults for sensitive data

Validator Security

• Keep your node software up to date
• Firewall RPC ports appropriately
• Use VPN for remote management
• Monitor node logs for suspicious activity
• Enable Nginx SSL/TLS for all RPC endpoints

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support & Community

For issues and discussions:

• Check existing documentation in the handbooks
• Review the Substrate Stack Exchange
• Engage with the Polkadot community

---