S\P

SDK Documentation

JavaScript/TypeScript SDK

Official JavaScript/TypeScript SDK for the SOVEREIGN\\PROVENANCE protocol

SOVEREIGN\PROVENANCE JavaScript/TypeScript SDK

Official JavaScript/TypeScript SDK for the SOVEREIGN\PROVENANCE protocol.

Installation

npm install @sovprovenance/sdk-js
# or
pnpm add @sovprovenance/sdk-js
# or
yarn add @sovprovenance/sdk-js

5-Minute Quickstart

Get started with SOVEREIGN\PROVENANCE in 5 minutes. This guide walks you through creating an identity, sealing content, issuing a passport, evaluating rights, and writing to the ledger.

Step 1: Initialize the Client

import { createSovProvClient } from '@sovprovenance/sdk-js';

const client = createSovProvClient({
  baseUrl: 'https://api.sovereign.provenance', // or 'http://localhost:3000' for local dev
  apiKey: 'your-api-key-here', // Get from your dashboard
});

Step 2: Create an Identity

// Create your sovereign identity
const identity = await client.createIdentity({
  publicKey: 'your-public-key', // Your cryptographic public key
  metadata: {
    name: 'Your Name',
    type: 'individual', // or 'institution', 'city', 'platform', 'ai_lab'
    website: 'https://yourwebsite.com',
  },
});

console.log('Identity created:', identity.id);
// Output: urn:sp:identity:abc123...

Step 3: Create a Passport (with Sample Metadata)

// First, generate a seal for your content
// (In production, you'd seal actual file content)
const seal = await client.generateSeal({
  content: 'your-artifact-content',
  contentType: 'image', // or 'text', 'audio', 'video', 'code', 'dataset'
  algorithm: 'sha256-frag-v1',
});

// Create a passport binding identity, seal, and metadata
const passport = await client.createPassport({
  identityId: identity.id,
  sealId: seal.id,
  metadata: {
    artifactType: 'image',
    title: 'My Digital Artwork',
    createdAt: new Date().toISOString(),
    tags: ['art', 'digital', 'nft'],
    description: 'A beautiful digital creation',
  },
});

console.log('Passport created:', passport.id);
// Output: urn:sp:passport:xyz789...

Step 4: Evaluate a Simple Accord

// Create an Accord with rights rules
const accord = await client.createAccord({
  attribution: 'required',
  derivatives: 'restricted', // Require permission for derivatives
  aiTraining: 'opt_out', // Don't allow AI training
  commercial: 'licensed', // Commercial use requires license
});

// Link the Accord to your passport
await client.updateRights(passport.id, {
  accordId: accord.id,
});

// Evaluate a proposed use
const evaluation = await client.evaluateUse(accord.id, {
  type: 'derivative',
  commercial: false,
  geographicRegion: 'us-west',
});

if (evaluation.allowed) {
  console.log('Use is allowed');
} else {
  console.log('Use denied:', evaluation.reason);
}

Step 5: Write a Ledger Event

// Write an event to the global ledger
const event = await client.writeEvent({
  type: 'passport_created',
  identity: identity.id,
  payload: {
    passportId: passport.id,
    artifactType: 'image',
  },
});

console.log('Event written to ledger:', event.id);

Complete Example

Here's the complete flow in one script:

import { createSovProvClient } from '@sovprovenance/sdk-js';

async function quickstart() {
  const client = createSovProvClient({
    baseUrl: 'https://api.sovereign.provenance',
    apiKey: process.env.SOVPROV_API_KEY!,
  });

  // 1. Create identity
  const identity = await client.createIdentity({
    publicKey: 'your-public-key',
    metadata: { name: 'Test Creator', type: 'individual' },
  });

  // 2. Generate seal
  const seal = await client.generateSeal({
    content: 'test-content',
    contentType: 'text',
  });

  // 3. Create passport
  const passport = await client.createPassport({
    identityId: identity.id,
    sealId: seal.id,
    metadata: {
      artifactType: 'text',
      title: 'Test Document',
      createdAt: new Date().toISOString(),
    },
  });

  // 4. Create and evaluate Accord
  const accord = await client.createAccord({
    attribution: 'required',
    derivatives: 'allowed',
    aiTraining: 'opt_out',
  });

  const evaluation = await client.evaluateUse(accord.id, {
    type: 'display',
    commercial: false,
  });

  console.log('Evaluation result:', evaluation);

  // 5. Write to ledger
  await client.writeEvent({
    type: 'passport_created',
    identity: identity.id,
    payload: { passportId: passport.id },
  });

  console.log('Quickstart complete!');
}

quickstart().catch(console.error);

Simulation Provenance Example (Fixtures)

The verification fixtures in tests/verification can be used to drive consistent payloads across tests and demos:

import { createSovProvClient } from '@sovprovenance/sdk-js';
import { readFile } from 'fs/promises';

async function sealFromFixtures() {
  const client = createSovProvClient({
    baseUrl: 'http://localhost:3000',
    apiKey: process.env.SOVPROV_API_KEY!,
  });

  const sealFixture = JSON.parse(
    await readFile('tests/verification/fixture-seal-request.json', 'utf-8')
  );
  const rightsFixture = JSON.parse(
    await readFile('tests/verification/fixture-rights-evaluation.json', 'utf-8')
  );
  const lineageFixture = JSON.parse(
    await readFile('tests/verification/fixture-lineage-event.json', 'utf-8')
  );

  const content = Buffer.from('example simulation output');
  const sealRequest = {
    ...sealFixture,
    content: content.toString('base64'),
  };

  const sealResult = await client.request('POST', '/provenance/seal', sealRequest);
  const artifactId = sealResult.artifactId;

  await client.request('POST', '/rights/evaluate', {
    ...rightsFixture,
    artifactId,
  });

  await client.addLineageEntry(artifactId, {
    ...lineageFixture,
    artifactId,
  });
}

sealFromFixtures().catch(console.error);

Error Handling

The SDK uses custom error types that provide clear, actionable information:

import { SovProvError } from '@sovprovenance/sdk-js';

try {
  await client.createPassport({ /* ... */ });
} catch (error) {
  if (error instanceof SovProvError) {
    console.error('Error code:', error.code);
    console.error('Reason:', error.reason);
    console.error('Details:', error.details);
    
    // Common error codes:
    // - UNAUTHORIZED: Missing or invalid API key
    // - VALIDATION_ERROR: Invalid request data
    // - NOT_FOUND: Resource not found
    // - RIGHTS_DENIED: Use denied by Accord
    // - INTERNAL_ERROR: Server error
  } else {
    console.error('Unexpected error:', error);
  }
}

Error Response Format

All errors follow this structure:

{
  "error": true,
  "code": "RIGHTS_DENIED",
  "reason": "Derivative use is forbidden by this Accord.",
  "details": {
    "accordId": "urn:sp:accord:001",
    "rule": "derivatives=forbidden"
  }
}
  • code: Machine-usable error code
  • reason: Human-readable explanation
  • details: Optional structured information

API Reference

See the developer documentation for complete API reference.

Next Steps