> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart Contracts Overview

> ZKScore smart contracts for on-chain identity, scoring, and trust systems

## What are ZKScore Smart Contracts?

ZKScore smart contracts provide the foundational infrastructure for on-chain identity, reputation scoring, achievements, and trust systems. Built on Ethereum and compatible with all EVM chains.

<CardGroup cols={2}>
  <Card title="IdentitySBT" icon="fingerprint" href="/contracts/identity-sbt/overview">
    Soulbound identity NFTs for unique user identification
  </Card>

  <Card title="ScoreCalculator" icon="chart-line" href="/contracts/score-calculator/overview">
    On-chain reputation scoring engine
  </Card>

  <Card title="AchievementRegistry" icon="trophy" href="/contracts/achievement-registry/overview">
    Achievement system and NFT badges
  </Card>

  <Card title="TrustRegistry" icon="shield" href="/contracts/trust-registry/overview">
    Attestation and trust verification system
  </Card>

  <Card title="ProtocolRegistry" icon="network-wired" href="/contracts/protocol-registry/overview">
    Protocol integration and module management
  </Card>
</CardGroup>

## Contract Architecture

```mermaid theme={null}
graph TB
    A[IdentitySBT] --> B[ScoreCalculator]
    A --> C[AchievementRegistry]
    A --> D[TrustRegistry]
    B --> E[Score Data]
    C --> F[Achievement NFTs]
    D --> G[Attestations]
    H[ProtocolRegistry] --> A
    H --> B
    H --> C
    H --> D
```

## Core Contracts

### IdentitySBT Contract

Non-transferable identity NFTs that represent unique individuals:

```solidity theme={null}
// Mint a new identity
function mint(address to, string calldata username) external returns (uint256);

// Activate an identity
function activate(uint256 tokenId) external;

// Check if address has identity
function hasIdentity(address account) external view returns (bool);
```

**Key Features:**

* Soulbound (non-transferable) NFTs
* Unique username system
* Activation mechanism
* Metadata management

### ScoreCalculator Contract

On-chain reputation scoring with real-time updates:

```solidity theme={null}
// Get current score
function getScore(address account) external view returns (uint256);

// Get score breakdown
function getScoreBreakdown(address account) external view returns (ScoreBreakdown memory);

// Update score (called by authorized updaters)
function updateScore(address account, uint256 newScore) external;
```

**Key Features:**

* Real-time score calculation
* Multi-dimensional scoring
* Historical score tracking
* Authorized updater system

### AchievementRegistry Contract

Gamified achievement system with NFT rewards:

```solidity theme={null}
// Create new achievement
function createAchievement(
    string calldata name,
    string calldata description,
    uint256 points
) external returns (uint256);

// Claim achievement
function claimAchievement(uint256 achievementId) external;

// Get user achievements
function getUserAchievements(address user) external view returns (uint256[] memory);
```

**Key Features:**

* Custom achievement creation
* NFT badge rewards
* Progress tracking
* Point system

### TrustRegistry Contract

Flexible attestation system for building trust:

```solidity theme={null}
// Create attestation
function createAttestation(
    address subject,
    string calldata schema,
    bytes calldata data
) external returns (uint256);

// Revoke attestation
function revokeAttestation(uint256 attestationId) external;

// Get attestations for subject
function getAttestations(address subject) external view returns (Attestation[] memory);
```

**Key Features:**

* Schema-based attestations
* Revocable attestations
* Multi-signature support
* Time-bound attestations

### ProtocolRegistry Contract

Integration hub for protocols and modules:

```solidity theme={null}
// Register protocol
function registerProtocol(
    string calldata name,
    address protocolAddress,
    bytes calldata metadata
) external;

// Get protocol info
function getProtocol(string calldata name) external view returns (Protocol memory);

// Update protocol
function updateProtocol(string calldata name, address newAddress) external;
```

## Integration Examples

### Direct Contract Integration

```typescript theme={null}
import { ethers } from 'ethers';
import { IdentitySBT__factory } from '@zkscore/contracts';

const provider = new ethers.providers.JsonRpcProvider(RPC_URL);
const signer = provider.getSigner();

const identitySBT = IdentitySBT__factory.connect(
  '0x...', // Contract address
  signer
);

// Mint identity
const tx = await identitySBT.mint('0x742d35...', 'alice');
await tx.wait();
```

### Ethers.js Integration

```typescript theme={null}
import { ethers } from 'ethers';
import { ZKScoreContracts } from '@zkscore/contracts';

const contracts = new ZKScoreContracts(provider, signer);

// Mint identity
await contracts.identity.mint('0x742d35...', 'alice');

// Get score
const score = await contracts.scores.getScore('0x742d35...');

// Create attestation
await contracts.trust.createAttestation(
  '0x742d35...',
  'kyc-verification',
  { verified: true, level: 'tier-2' }
);
```

### Viem Integration

```typescript theme={null}
import { createPublicClient, createWalletClient } from 'viem';
import { zkScoreAbi } from '@zkscore/contracts';

const publicClient = createPublicClient({
  chain: mainnet,
  transport: http(),
});

const walletClient = createWalletClient({
  chain: mainnet,
  transport: http(),
});

// Read score
const score = await publicClient.readContract({
  address: '0x...',
  abi: zkScoreAbi,
  functionName: 'getScore',
  args: ['0x742d35...'],
});

// Mint identity
await walletClient.writeContract({
  address: '0x...',
  abi: identitySbtAbi,
  functionName: 'mint',
  args: ['0x742d35...', 'alice'],
});
```

### Wagmi Integration

```tsx theme={null}
import { useContract, useContractWrite } from 'wagmi';
import { zkScoreConfig } from '@zkscore/contracts';

function MintIdentity() {
  const { write } = useContractWrite({
    address: zkScoreConfig.identitySbt,
    abi: identitySbtAbi,
    functionName: 'mint',
  });

  return (
    <button onClick={() => write({ args: ['0x742d35...', 'alice'] })}>
      Mint Identity
    </button>
  );
}
```

## Network Deployments

<CardGroup cols={3}>
  <Card title="Ethereum Mainnet" icon="ethereum">
    **IdentitySBT**: `0x...`\
    **ScoreCalculator**: `0x...`\
    **AchievementRegistry**: `0x...`
  </Card>

  <Card title="Base" icon="circle">
    **IdentitySBT**: `0x...`\
    **ScoreCalculator**: `0x...`\
    **AchievementRegistry**: `0x...`
  </Card>

  <Card title="Polygon" icon="triangle">
    **IdentitySBT**: `0x...`\
    **ScoreCalculator**: `0x...`\
    **AchievementRegistry**: `0x...`
  </Card>

  <Card title="Arbitrum" icon="layer-group">
    **IdentitySBT**: `0x...`\
    **ScoreCalculator**: `0x...`\
    **AchievementRegistry**: `0x...`
  </Card>

  <Card title="Optimism" icon="layer-group">
    **IdentitySBT**: `0x...`\
    **ScoreCalculator**: `0x...`\
    **AchievementRegistry**: `0x...`
  </Card>

  <Card title="BSC" icon="link">
    **IdentitySBT**: `0x...`\
    **ScoreCalculator**: `0x...`\
    **AchievementRegistry**: `0x...`
  </Card>
</CardGroup>

## Security Features

<CardGroup cols={2}>
  <Card title="Access Control" icon="shield">
    Role-based permissions and multi-sig support
  </Card>

  <Card title="Upgradeable" icon="arrow-up">
    Proxy patterns for contract upgrades
  </Card>

  <Card title="Pausable" icon="pause">
    Emergency pause functionality
  </Card>

  <Card title="Audited" icon="check-double">
    Comprehensive security audits
  </Card>
</CardGroup>

## Gas Optimization

* **Batch Operations**: Combine multiple calls in single transaction
* **Storage Optimization**: Efficient data structures
* **Event Optimization**: Minimal event emissions
* **Proxy Patterns**: Upgradeable without migration

## Testing

### Hardhat Integration

```typescript theme={null}
import { ethers } from 'hardhat';
import { ZKScoreContracts } from '@zkscore/contracts';

describe('ZKScore Contracts', () => {
  let contracts: ZKScoreContracts;

  beforeEach(async () => {
    contracts = await ZKScoreContracts.deploy();
  });

  it('should mint identity', async () => {
    await contracts.identity.mint('0x742d35...', 'alice');
    const hasIdentity = await contracts.identity.hasIdentity('0x742d35...');
    expect(hasIdentity).to.be.true;
  });
});
```

### Foundry Integration

```solidity theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Test.sol";
import "../src/IdentitySBT.sol";

contract IdentitySBTTest is Test {
    IdentitySBT identitySBT;

    function setUp() public {
        identitySBT = new IdentitySBT();
    }

    function testMintIdentity() public {
        identitySBT.mint(address(this), "alice");
        assertTrue(identitySBT.hasIdentity(address(this)));
    }
}
```

## Event Monitoring

```typescript theme={null}
// Listen for identity minted events
const filter = identitySBT.filters.IdentityMinted();
identitySBT.on(filter, (to, tokenId, username, event) => {
  console.log(`Identity minted: ${username} (${tokenId}) to ${to}`);
});

// Listen for score updates
const scoreFilter = scoreCalculator.filters.ScoreUpdated();
scoreCalculator.on(scoreFilter, (account, newScore, oldScore, event) => {
  console.log(`Score updated for ${account}: ${oldScore} → ${newScore}`);
});
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Error Handling" icon="exclamation-triangle">
    Always check return values and handle reverts
  </Card>

  <Card title="Gas Estimation" icon="gauge">
    Estimate gas before transactions
  </Card>

  <Card title="Event Listening" icon="ear">
    Monitor events for state changes
  </Card>

  <Card title="Batch Operations" icon="layer-group">
    Combine multiple calls when possible
  </Card>
</CardGroup>

## Common Patterns

### Identity Verification

```typescript theme={null}
async function verifyIdentity(address: string): Promise<boolean> {
  try {
    const hasIdentity = await identitySBT.hasIdentity(address);
    if (!hasIdentity) return false;
    
    const tokenId = await identitySBT.getTokenId(address);
    const isActive = await identitySBT.isActive(tokenId);
    
    return isActive;
  } catch (error) {
    console.error('Identity verification failed:', error);
    return false;
  }
}
```

### Score Gating

```typescript theme={null}
async function checkScoreGate(address: string, minScore: number): Promise<boolean> {
  try {
    const score = await scoreCalculator.getScore(address);
    return score >= minScore;
  } catch (error) {
    console.error('Score check failed:', error);
    return false;
  }
}
```

### Achievement Tracking

```typescript theme={null}
async function trackAchievementProgress(address: string, achievementId: number) {
  const progress = await achievementRegistry.getProgress(address, achievementId);
  const isEligible = await achievementRegistry.isEligible(address, achievementId);
  
  return { progress, isEligible };
}
```

## Next Steps

<Steps>
  <Step title="Choose Integration Method">
    Select direct contracts, Ethers, Viem, or Wagmi
    [Integration Guide →](/contracts/deployment)
  </Step>

  <Step title="Deploy Contracts">
    Deploy to your preferred network
    [Deployment →](/contracts/deployment)
  </Step>

  <Step title="Start Building">
    Integrate contracts into your application
    [Examples →](/contracts/examples)
  </Step>

  <Step title="Test Thoroughly">
    Use our testing utilities and examples
    [Testing →](/contracts/examples/testing)
  </Step>
</Steps>

## Support & Resources

<CardGroup cols={2}>
  <Card title="Contract Addresses" icon="map-marker" href="/contracts/addresses">
    All deployed contract addresses
  </Card>

  <Card title="ABI Files" icon="code" href="https://github.com/metalanddev/ZKScoreEVM/tree/main/contracts/abi">
    Contract ABI files
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/metalanddev/ZKScoreEVM">
    Source code and issues
  </Card>

  <Card title="Discord" icon="discord" href="https://discord.gg/zkscore">
    Developer community
  </Card>
</CardGroup>

***

<Note>
  **Need help?** Check our [Discord](https://discord.gg/zkscore) or [GitHub issues](https://github.com/metalanddev/ZKScoreEVM/issues)
</Note>