S\P

Developer Docs

Quickstart Guide

Get up and running in 5 minutes. Create your first identity, seal, and passport.

Developer Quickstart

Get started with SOVEREIGN\PROVENANCE in 5 minutes.

Prerequisites

  • Node.js 18+
  • Go 1.21+
  • Rust (latest stable)
  • PostgreSQL 14+
  • pnpm
  • Docker & Docker Compose (optional)

Quick Start

1. Clone and Install

git clone <repository-url>
cd mirror-sovereign-1
pnpm install

2. Start Services

Option A: Docker Compose (Recommended)

make docker-up

Option B: Manual

# Terminal 1: PostgreSQL
docker run -d -p 5432:5432 \
  -e POSTGRES_DB=sovprovenance \
  -e POSTGRES_USER=sovprovenance \
  -e POSTGRES_PASSWORD=sovprovenance \
  postgres:15-alpine

# Terminal 2: Run migrations
pnpm migrate

# Terminal 3: Ledger service
cd services/ledger
go run cmd/ledger/main.go

# Terminal 4: API service
cd apps/api
pnpm dev

# Terminal 5: Guardian Node (optional)
cd apps/guardian-node
go run cmd/guardian-node/main.go

3. Verify Services

# API health
curl http://localhost:3000/health

# Ledger health
curl http://localhost:8082/internal/ledger/health

# Guardian Node status
curl http://localhost:8083/v1/node/status

Using the SDK

Install SDK

npm install sp-sdk

Or from the monorepo:

cd packages/sp-sdk
pnpm install
pnpm build

Basic Usage

import { configure, seal, verify, trackTransformation } from 'sp-sdk';

// Configure the SDK
configure({
  baseUrl: 'http://localhost:3000',
  apiKey: 'dev-key-1',
  projectId: 'my-project',
});

// Seal an artifact
const result = await seal('./my-file.png');
console.log('Artifact ID:', result.artifactId);
console.log('Hash:', result.hash);
console.log('Verification URL:', result.verificationUrl);

// Verify an artifact
const verification = await verify('./my-file.png');
if (verification.verified) {
  console.log('Verified:', verification.artifactId);
}

// Track a transformation
await trackTransformation({
  parentArtifactId: 'parent-id',
  childFileOrBuffer: './transformed-file.png',
  action: 'transformed',
  metadata: { tool: 'image-processor' },
});

Using the CLI

Install CLI

npm install -g sp-cli

Or use with npx:

npx sp-cli <command>

Basic Usage

# Initialize
sp init --project-id my-project --api-key my-key

# Seal a file
sp seal ./document.pdf
# Output:
# ✅ File sealed
#    Artifact ID: artifact_1234567890
#    Hash: abc123def456...
#    Verification URL: https://sovereign.provenance/verify?hash=abc123...

# Verify a file
sp verify ./document.pdf

# View lineage
sp lineage artifact_1234567890

See the SDK README and CLI README for more details.

API Examples

Create Identity

curl -X POST http://localhost:3000/api/v1/identity \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dev-key-1" \
  -d '{
    "name": "Demo Creator",
    "type": "creator",
    "email": "demo@example.test",
    "publicKey": "test-key-123",
    "trustSignals": [
      { "type": "email_verified", "strength": 0.6 }
    ]
  }'

Create Passport

curl -X POST http://localhost:3000/api/v1/passport \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dev-key-1" \
  -d '{
    "identityId": "urn:sp:identity:...",
    "sealId": "urn:sp:seal:...",
    "metadata": {
      "artifactType": "image",
      "createdAt": "2024-01-01T00:00:00Z",
      "tags": ["art"]
    }
  }'

Query Ledger Events

curl http://localhost:3000/api/v1/ledger/events?limit=10

Next Steps