Quick Start Guide

Welcome to the Cultura SDK! This toolkit enables developers to interact with Cultura, a Layer 2 Ethereum blockchain serving as the global registry for human creativity and intellectual property. Cultura ensures transparent licensing, revenue sharing, and secure provenance for creative works. This SDK provides a comprehensive set of tools for working with Digital Assets, Rights Attestations, and Licensing in the Cultura ecosystem.

Installation

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

Quick Start

The SDK can be configured for different environments and with different wallet connections:

import { CulturaSDK } from '@cultura/sdk'

// Create SDK instance with default configuration (testnet) read-only
const sdk = CulturaSDK.create()

// Create SDK instance for specific environment
const devnetSdk = CulturaSDK.create({ chain: 'devnet' })
const localSdk = CulturaSDK.create({ chain: 'local' })

// Create SDK instance with wallet connection (uses testnet by default)
const walletSdk = CulturaSDK.createWithWallet(window.ethereum)

// Create SDK instance with wallet connection and specific chain
const localWalletSdk = CulturaSDK.createWithWallet(window.ethereum, {
  chain: 'local',
  // You can provide other configuration options here
})

// Create SDK instance with wallet connection, specific chain and account address
const walletWithAddressSdk = CulturaSDK.createWithWallet(window.ethereum, {
  chain: 'testnet',
  account: '0x123...' as `0x${string}`,
})

// Create SDK instance with specfific account address (read-only for transactions)
const addressSdk = CulturaSDK.createWithAccount('0x123...', { chain: 'testnet' })

// Create SDK instance with an account from a private key (full signing capability)
import { privateKeyToAccount } from 'viem/accounts'
const account = privateKeyToAccount('0xYourPrivateKeyHere')
const privateKeySdk = CulturaSDK.createWithAccount(account, { chain: 'testnet' })

Environments

The SDK supports the following environments:

local - Local development environment
devnet - Cultura Devnet (subject to heavy changes and frequent resets)
testnet (default) - Cultura Testnet (stable environment for testing)

The environment is set at SDK instantiation time and doesn’t rely on environment variables. Always explicitly specify the environment you want to use when creating the SDK instance.

Usage with Frontend Frameworks

React Example

import { createContext, useContext, useEffect, useState } from "react";
import { CulturaSDK, utils } from "@cultura/sdk";
import { useAuth } from "your-auth-provider"; // Replace with your actual auth hook
const { getChainName } = utils;

const SDKContext = createContext<CulturaSDK | null>(null);

export function useSDK() {
  const context = useContext(SDKContext);
  // Don't throw an error, just return null if not in provider
  return context;
}

export function SDKProvider({ children }: { children: React.ReactNode }) {
  const { ready, isConnected, connectedWallet, address } = useAuth();
  const [sdk, setSdk] = useState<CulturaSDK | null>(null);

  useEffect(() => {
    if (!ready || !isConnected || !connectedWallet || !address) {
      setSdk(null);
      return;
    }

    const chainId = parseChainId(connectedWallet.chainId); // Implement parseChainId based on your needs

    // Create SDK with wallet connection
    const newSdk = CulturaSDK.createWithWallet(window.ethereum, {
      chain: getChainName(chainId),
      account: address as `0x${string}`,
    });

    setSdk(newSdk);
  }, [ready, isConnected, connectedWallet, address, connectedWallet?.chainId]);

  return <SDKContext.Provider value={sdk}>{children}</SDKContext.Provider>;
}

Core Features

Digital Asset Management: Create, mint, and manage Digital Assets
Rights Attestations: Attest to rights ownership and verify attestations
Licensing: License Digital Assets and manage licensing rights
Query: Query indexed blockchain data via The Graph

Configuration Options

When creating an SDK instance, you can provide a configuration object with the following options:

{
  // Chain identifier - can be a name or chain ID
  chain: 'testnet', // or 'devnet', 'local', or a chain ID

  // Transport for blockchain communication
  transport: http('https://rpc-url...'),

  // Wallet client (if you have already created one)
  wallet: walletClient,

  // Account to use for transactions
  account: '0x123...' or accountObject,

  // Optional contract addresses (overrides defaults for the selected chain)
  contracts: {
    attestationService: '0x...',
    // ... other contract addresses
  }
}

SDK Initialization Methods

The Cultura SDK offers different initialization methods depending on your use case:

Read-Only Access: `create()`

// Create SDK instance with default configuration (testnet)
const sdk = CulturaSDK.create()

// Create SDK instance for specific environment
const devnetSdk = CulturaSDK.create({ chain: 'devnet' })
const localSdk = CulturaSDK.create({ chain: 'local' })

The create() method initializes a read-only SDK instance without wallet connection. Use this when:

You only need to query or read data from the blockchain (like token information, attestation details)
You’re building an application that displays blockchain data without write operations
You need a fallback mode when a wallet isn’t available
You’re working on server-side applications that only need to read data

Note that operations requiring transaction signing (like minting assets, creating attestations, or transferring tokens) will throw errors if attempted with a read-only instance.

Wallet-Connected: `createWithWallet()` and `createWithAccount()`

// Create SDK instance with wallet connection (uses testnet by default)
const walletSdk = CulturaSDK.createWithWallet(window.ethereum)

// Create SDK instance with wallet connection and specific chain
const localWalletSdk = CulturaSDK.createWithWallet(window.ethereum, {
  chain: 'local',
  // You can provide other configuration options here
})

// Create SDK instance with specific account address (read-only for transactions)
const addressSdk = CulturaSDK.createWithAccount('0x123...', { chain: 'testnet' })

// Create SDK instance with an account from a private key (full signing capability)
import { privateKeyToAccount } from 'viem/accounts'
const account = privateKeyToAccount('0xYourPrivateKeyHere')
const privateKeySdk = CulturaSDK.createWithAccount(account, { chain: 'testnet' })

Use these methods when your application needs to perform transactions like:

Creating and minting Digital Assets
Managing rights attestations
Approving operations
Transferring tokens
Any other operation that requires transaction signing

Query Example

Here’s a quick example of querying data with a read-only SDK instance:

import { CulturaSDK } from '@cultura/sdk'

// Create a read-only SDK instance for local development
const sdk = CulturaSDK.create({ chain: 'local' })

// Get the query client
const queryClient = sdk.query

// Example 1: Get all verified rights
async function getVerifiedRights() {
  const verifiedRights = await queryClient.verifiedRights.getAll(10, 0)
  console.log(`Found ${verifiedRights.length} verified rights:`)
  verifiedRights.forEach((right) => {
    console.log(`- ID: ${right.id}, Grade: ${right.grade}`)
    console.log(`  Asset Name: ${right.digitalAsset?.assetName || 'Unnamed'}`)
    console.log(`  Bond Amount: ${right.currentBondAmount}`)
    console.log(`  Is Verified: ${right.isVerified}`)
  })
}

// Example 2: Get all digital assets
async function getDigitalAssets() {
  const assets = await queryClient.digitalAsset.getAll(10, 0)
  console.log(`Found ${assets.length} digital assets:`)
  assets.forEach((asset) => {
    console.log(`- Token ID: ${asset.tokenId}`)
    console.log(`  Owner: ${asset.owner.address}`)
    console.log(`  Name: ${asset.assetName || 'Unnamed'}`)
    console.log(`  Licensed Asset: ${asset.isLicensedAsset ? 'Yes' : 'No'}`)
  })
}

// Example 3: Get verified rights for a specific owner
async function getRightsByOwner(ownerAddress) {
  const ownerRights = await queryClient.verifiedRights.getByOwner(ownerAddress)
  console.log(`Found ${ownerRights.length} rights for this owner:`)
  ownerRights.forEach((right) => {
    console.log(`- ID: ${right.id}, Grade: ${right.grade}`)
    if (right.digitalAsset) {
      console.log(`  Asset: ${right.digitalAsset.assetName || 'Unnamed'}`)
    }
  })
}

// Example 4: Get licensed assets derived from a parent asset
async function getLicensedAssets(parentAssetId, contractAddress) {
  const licensedAssets = await queryClient.digitalAsset.getLicensedAssets(
    parentAssetId,
    contractAddress
  )
  console.log(`Found ${licensedAssets.length} licensed assets:`)
  licensedAssets.forEach((asset) => {
    console.log(`- Token ID: ${asset.tokenId}`)
    console.log(`  Owner: ${asset.owner.address}`)
    console.log(`  Name: ${asset.assetName || 'Unnamed'}`)
  })
}

// Run examples
async function runExamples() {
  try {
    await getVerifiedRights()
    await getDigitalAssets()
    await getRightsByOwner('0x70997970C51812dc3A010C7d01b50e0d17dc79C8')
    await getLicensedAssets('1', '0x5FbDB2315678afecb367f032d93F642f64180aa3')
  } catch (error) {
    console.error('Error running examples:', error)
  }
}

runExamples()

Examples

For more comprehensive, in-depth examples of SDK usage flows, check out the examples in the examples/ directory:

query-examples.ts: Demonstrates various query operations using the SDK
verified-rights-licensing-flow.ts: Shows a complete flow for verified rights licensing

You can run these examples to see the SDK in action and understand common integration patterns:

# Run the rights licensing flow example
npm run example
# or
yarn example
# or
pnpm example

# Run the query examples
npm run example:query
# or
yarn example:query
# or
pnpm example:query

License

MIT

​Quick Start Guide

​Installation

​Quick Start

​Environments

​Usage with Frontend Frameworks

​React Example

​Core Features

​Configuration Options

​SDK Initialization Methods

​Read-Only Access: create()

​Wallet-Connected: createWithWallet() and createWithAccount()

​Query Example

​Examples

​License