Spiral ID SDK

The complete toolkit for integrating decentralized identity, reputation, and privacy into your Web3 applications.

What is Spiral ID?

Spiral ID is a decentralized identity protocol that empowers users to own, control, and leverage their digital identity across the Web3 ecosystem. It goes beyond simple authentication by building a dynamic reputation system based on on-chain activities.

This SDK is the easiest way to integrate Spiral ID's powerful features into your decentralized application (dApp), providing a seamless experience for both developers and end-users.

Core Features

• ✨ Seamless Web3 Authentication: Effortlessly integrate "Sign-In with Ethereum" (SIWE) for secure, wallet-based authentication.
• � Lightning-Fast Identity Creation: Onboard users in under 30 seconds with a gasless, seamless experience.
• 🛡️ Biometric-Free Privacy: Ensure maximum user privacy and data protection with our identity verification process that requires no biometric data.
• �💎 On-Chain Reputation & Identity: Utilize the $SPID token to allow users to build their on-chain reputation, create a unique Spiral ID, and unlock new possibilities.
• 🔒 Privacy via ZK-Proofs: Verify user credentials and data points with Zero-Knowledge Proofs (using Groth16 and EdDSA), ensuring user privacy is always protected.
• � Premium Profiles: Enable users to create premium, feature-rich profiles by burning $SPID, offering them exclusive benefits and deeper engagement within your platform.
• 📦 Fully-Typed & Production-Ready: Built with TypeScript for a robust and predictable development experience.

Installation

Get started by adding the Spiral ID SDK to your project:

npm install @spiralid/sdk
# or
yarn add @spiralid/sdk
# or
pnpm add @spiralid/sdk

Getting Started: A Complete Example

Here’s a complete, practical example of how to use the SDK. This guide will walk you through initializing the SDK, authenticating a user, and interacting with the Spiral ID protocol.

import { SpiralSDK } from '@spiralid/sdk';

// --- Step 1: Initialize the SDK ---
// Configure the SDK with your application's details.
// You can find the correct contract addresses for each network in our documentation.
const sdk = new SpiralSDK({
  apiUrl: 'https://api.spiralid.dev',
  chainId: 11155111, // Sepolia Testnet
  spidContractAddress: '0xYourSpidContractAddress', // Replace with the official SPID token contract address
});

async function main() {
  try {
    // --- Step 2: Authenticate the User ---
    // This will trigger a "Sign-In with Ethereum" prompt in the user's wallet.
    console.log('Attempting to authenticate...');
    const authResponse = await sdk.auth.web3.authenticate();
    console.log('✅ Authentication successful! Token:', authResponse.token);

    // Set the received token for subsequent authenticated API calls
    sdk.setAuthToken(authResponse.token);
    const userAddress = authResponse.address;
    console.log(`Authenticated user address: ${userAddress}`);

    // --- Step 3: Interact with the SPID Token ---
    // Let's check the user's SPID token balance.
    console.log(`
Checking SPID balance for ${userAddress}...`);
    const balance = await sdk.contracts.spid.getBalance(userAddress);
    console.log(`💰 User has a balance of ${balance} SPID.`);

    // --- Step 4: Create a Spiral ID & Build Reputation ---
    // To create a Spiral ID, a user burns a certain amount of SPID tokens.
    // This action contributes to their on-chain reputation.
    const spiralId = `user-${Date.now()}`; // A unique identifier for the user
    const amountToBurn = '50'; // Amount of SPID to burn
    
    console.log(`
Attempting to create Spiral ID "${spiralId}" by burning ${amountToBurn} SPID...`);
    // Note: This will require the user to approve the transaction in their wallet.
    const txHash = await sdk.contracts.spid.burnForSpiral({
      spiralId,
      amount: amountToBurn,
    });
    console.log(`🔥 Spiral ID created successfully! Transaction hash: ${txHash}`);

    // You can also directly increase a user's reputation
    await sdk.contracts.spid.increaseReputation(10);
    const reputation = await sdk.contracts.spid.getReputation(userAddress);
    console.log(`📈 User's new reputation score: ${reputation}`);

  } catch (error) {
    console.error('❌ An error occurred:', error);
  }
}

main();

Roadmap

Our vision is to make Spiral ID the universal, cross-chain standard for on-chain reputation. Here are some of the features we are planning for the future:

• Cross-Chain Reputation: Aggregate a user's reputation across multiple blockchains (Ethereum, Polygon, Solana, etc.) into a single, unified Spiral ID score.
• Reputation Composability: Allow other protocols to, with user permission, write to the Spiral ID reputation score. This will position Spiral ID as the foundational reputation layer of Web3.
• UI Component Library: A library of pre-built React components to easily display Spiral ID profiles, reputation scores, and more.

Project Structure

The SDK is organized as follows:

• src/: The main source code of the SDK.
  • api/: Client for the Spiral ID backend.
  • auth/: Authentication logic (SIWE).
  • contracts/: Interacting with smart contracts.
  • zk/: Zero-Knowledge Proof utilities.
  • __tests__/: All tests for the SDK.
• dist/: The compiled JavaScript output.
• examples/: (Coming Soon) Sample projects using the SDK.

The Spiral ID SDK is organized into logical modules to make it easy to find the functionality you need.

• sdk.auth: Handles all authentication-related logic, primarily through Sign-In with Ethereum (SIWE).
• sdk.contracts: Provides methods to interact directly with the Spiral ID smart contracts, such as spid for token operations.
• sdk.api: A client for making authenticated requests to the Spiral ID backend API.
• sdk.zk: Contains utilities for generating and verifying Zero-Knowledge Proofs, enabling privacy-preserving features.

Contributing

We welcome contributions from the community! If you'd like to help improve the Spiral ID SDK, please follow these steps:

1. Fork the repository on GitHub.
2. Clone your fork to your local machine.
3. Create a new branch for your changes.
4. Make your changes and add tests for them.
5. Ensure all tests pass by running npm test.
6. Submit a pull request with a clear description of your changes.

Before starting, please open an issue to discuss your planned changes.

License

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