# WIA-EDU-011 Digital Credential Standard v1.2

## Phase 3: Protocol & Blockchain Integration

**Status:** ✅ Complete
**Version:** 1.2.0
**Date:** 2025-01-15
**Philosophy:** 弘益人間 (Benefit All Humanity)

---

## 1. Overview

Phase 3 extends Phase 2 by defining blockchain anchoring protocols, smart contract specifications, and decentralized verification mechanisms. This ensures credentials have immutable, publicly-verifiable proofs.

## 2. Scope

Phase 3 covers:
- Blockchain anchoring protocol
- Smart contract specifications
- Multi-chain support
- Revocation lists on-chain
- Gas optimization strategies
- Decentralized storage integration

## 3. Blockchain Requirements

### 3.1 Supported Networks

**Primary Networks:**
- Ethereum Mainnet
- Polygon (MATIC)
- Arbitrum

**Testnet Support:**
- Sepolia (Ethereum)
- Mumbai (Polygon)

### 3.2 Smart Contract Architecture

**Core Contracts:**
- `WIACredentialRegistry.sol` - Credential anchoring
- `WIAIssuerRegistry.sol` - Trusted issuers
- `WIARevocationList.sol` - Revocation management

## 4. Credential Anchoring Protocol

### 4.1 Hash Anchoring

**Process:**
1. Generate SHA-256 hash of credential JSON-LD
2. Create Merkle tree for batch credentials
3. Anchor Merkle root to blockchain
4. Store transaction hash in credential proof

**Hash Format:**
```
0x{sha256(canonicalized-json-ld)}
```

### 4.2 Smart Contract Integration

**Solidity Interface:**
```solidity
interface IWIACredentialRegistry {
    function anchorCredential(
        bytes32 credentialHash,
        string calldata did,
        uint256 issuanceDate
    ) external returns (uint256 credentialId);

    function verifyCredential(
        bytes32 credentialHash
    ) external view returns (bool exists, uint256 timestamp);

    function revokeCredential(
        bytes32 credentialHash,
        string calldata reason
    ) external;
}
```

## 5. Batch Issuance Optimization

### 5.1 Merkle Tree Batching

**Benefits:**
- Issue 100+ credentials in single transaction
- Cost: $0.01-$0.05 per credential
- Proof size: ~1 KB per credential

**Merkle Proof Structure:**
```json
{
  "merkleRoot": "0x...",
  "proof": [
    "0x...",
    "0x...",
    "0x..."
  ],
  "leafIndex": 42
}
```

### 5.2 Gas Optimization

**Strategies:**
- Batch transactions during low gas periods
- Use EIP-1559 gas pricing
- Implement on Polygon for <$0.10 per batch
- Store only hashes, not full data

## 6. Revocation Management

### 6.1 Bitmap-Based Revocation

**RevocationList2020 Implementation:**
```solidity
contract WIARevocationList {
    mapping(uint256 => uint256) private revocationBitmap;

    function revoke(uint256 credentialIndex) external onlyIssuer {
        uint256 bucket = credentialIndex / 256;
        uint256 position = credentialIndex % 256;
        revocationBitmap[bucket] |= (1 << position);
    }

    function isRevoked(uint256 credentialIndex)
        external view returns (bool) {
        uint256 bucket = credentialIndex / 256;
        uint256 position = credentialIndex % 256;
        return (revocationBitmap[bucket] & (1 << position)) != 0;
    }
}
```

### 6.2 Status List 2021

**Privacy-Preserving Revocation:**
- Herd privacy for revocation checks
- Bitstring compression
- Efficient storage: 131,072 credentials per list

## 7. Decentralized Storage

### 7.1 IPFS Integration

**Credential Storage:**
```
ipfs://{CID}
```

**Benefits:**
- Decentralized, immutable storage
- Content-addressed retrieval
- Redundancy through pinning services

### 7.2 Arweave for Permanent Storage

**Long-term Archival:**
- One-time payment for permanent storage
- Historical credential lookups
- Compliance with retention policies

## 8. Multi-Chain Support

### 8.1 Cross-Chain Verification

**Supported Bridges:**
- LayerZero for omnichain messaging
- Chainlink CCIP for cross-chain verification
- Wormhole for multi-chain state

### 8.2 Chain Selection Strategy

| Use Case | Recommended Chain | Cost | Speed |
|----------|------------------|------|-------|
| High-value degrees | Ethereum | $5-20 | 15s |
| Batch issuance | Polygon | $0.01 | 2s |
| Enterprise | Arbitrum | $0.50 | 1s |
| Testing | Sepolia | Free | 15s |

## 9. Blockchain Verification Protocol

### 9.1 On-Chain Verification

**Steps:**
1. Extract credential hash from VC
2. Query blockchain for hash existence
3. Verify timestamp matches issuance date
4. Check issuer DID is authorized
5. Verify revocation status

**Web3.js Example:**
```javascript
const registry = new web3.eth.Contract(ABI, ADDRESS);
const result = await registry.methods
  .verifyCredential(credentialHash)
  .call();

if (result.exists) {
  console.log('Credential anchored at:', result.timestamp);
}
```

## 10. Event Logging

### 10.1 Smart Contract Events

```solidity
event CredentialIssued(
    bytes32 indexed credentialHash,
    string did,
    uint256 timestamp
);

event CredentialRevoked(
    bytes32 indexed credentialHash,
    string reason,
    uint256 timestamp
);
```

### 10.2 Event Indexing

- The Graph for blockchain data indexing
- SubQuery for multi-chain support
- Custom indexers for institution-specific needs

## 11. Security Considerations

### 11.1 Smart Contract Security

**Best Practices:**
- OpenZeppelin security libraries
- Multi-signature wallets for admin functions
- Time-locked upgrades
- Circuit breakers for emergency stops
- Regular security audits

### 11.2 Key Management

**Hardware Security Modules (HSM):**
- Store institutional signing keys
- AWS KMS, Azure Key Vault support
- Multi-party computation (MPC) wallets

## 12. Cost Analysis

### 12.1 Transaction Costs

**Polygon (Recommended):**
- Single credential: $0.01-$0.05
- Batch (100 credentials): $0.50-$2.00
- Revocation: $0.01-$0.03

**Ethereum Mainnet:**
- Single credential: $5-$50 (varies)
- Batch (100 credentials): $20-$200
- Revocation: $5-$30

## 13. Compliance

Phase 3 MUST comply with:
- ✅ EIP-712 (Typed structured data hashing)
- ✅ EIP-1559 (Gas pricing)
- ✅ EIP-2535 (Diamond standard for upgrades)
- ✅ OpenZeppelin security standards
- ✅ Blockchain data privacy regulations

---

**Philosophy:** 弘益人間 (Benefit All Humanity)

*WIA-EDU-011 Digital Credential Standard*

© 2025 MIT License