Skip to main content

​
Royalty Management

The SDK provides invoice generation functionality to create mock invoice data for testing and development: 
import { SpaceportSDK } from '@spaceport/sdk'

async function generateInvoiceData() {
  const sdk = SpaceportSDK.createWithAccount(account, {
    chain: 'devnet',
    apiKey: process.env.SDK_API_KEY,
  })

  // Generate mock invoice data for testing
  const assetPlatformId = `roblox-${Math.floor(Math.random() * 1000000000)}`
  const csvResult = await sdk.invoices.generateMockInvoiceData({
    count: 8, // Number of invoices per quarter
    startYear: 2025, // Starting year for invoice data
    quarters: 4, // Number of quarters to generate
    assetPlatformId: assetPlatformId, // Platform-specific asset ID
  })

  // Create a File object from the CSV content
  const csvFile = new File([csvResult.csvContent], 'mock-invoices.csv', { type: 'text/csv' })

  console.log(
    `Generated ${csvResult.totalInvoices} invoices across ${csvResult.quarterRanges.length} quarters`
  )

  // Access quarter ranges for period-based operations
  csvResult.quarterRanges.forEach((quarter, index) => {
    console.log(`Q${index + 1}: ${quarter.start.toISOString()} - ${quarter.end.toISOString()}`)
  })

  return { csvFile, csvResult }
}

​
Invoice Generation Methods

  • invoices.generateMockInvoiceData(params): Generates mock invoice data with specified parameters
    • count: Number of invoices to generate per quarter
    • startYear: Starting year for the invoice data
    • quarters: Number of quarters to generate data for
    • assetPlatformId: Platform-specific asset identifier (e.g., Roblox asset ID)
The generated CSV data includes realistic invoice information that can be used for testing royalty registration and payment workflows. The SDK provides comprehensive royalty management functionality including registration, payment, and approval workflows: 
import { SpaceportSDK } from '@spaceport/sdk'

async function manageRoyalties() {
  const licenseeSDK = SpaceportSDK.createWithAccount(licenseeAccount, {
    chain: 'devnet',
    apiKey: process.env.SDK_API_KEY,
  })

  const licensorSDK = SpaceportSDK.createWithAccount(licensorAccount, {
    chain: 'devnet',
    apiKey: process.env.SDK_API_KEY,
  })

  // 1. Register royalties from CSV invoice data
  const registrationResult = await licenseeSDK.royalties.register({
    csvFile: csvFile, // File object containing invoice data
    productIds: productIds, // Array of product IDs
  })

  // 2. Monitor registration job
  if (registrationResult.success) {
    const jobStatus = await licenseeSDK.utils.pollJobStatus(registrationResult.jobId, {
      timeout: 300000, // 5 minutes
      interval: 3000, // 3 seconds
    })
  }

  // 3. Pay off-chain royalties (by licensee)
  const payResult = await licenseeSDK.royalties.payOffchain({
    coreProductIds: productIds.map((id) => id.toString()),
  })

  // 4. Accept off-chain royalties (by licensor)
  const acceptanceInputs = quarterRanges.map((quarter) => ({
    coreProductIds: productIds.map((id) => id.toString()),
    periodStart: quarter.start,
    periodEnd: quarter.end,
  }))

  const acceptResult = await licensorSDK.royalties.acceptOffchain(acceptanceInputs)

  // 5. Deny off-chain royalties (by licensor)
  const denialInputs = quarterRanges.map((quarter) => ({
    coreProductIds: productIds.map((id) => id.toString()),
    periodStart: quarter.start,
    periodEnd: quarter.end,
  }))

  const denyResult = await licensorSDK.royalties.denyOffchain(denialInputs)
}

​
Royalty Management Methods

  • royalties.register(params): Registers royalties from CSV invoice data
    • Imports CSV invoices into the database
    • Groups invoices by quarters and calculates total revenue
    • Generates signatures client-side using the Cultura SDK
    • Submits royalty registration with real invoice-based periods
  • royalties.payOffchain(params): Initiates off-chain royalty payments
    • coreProductIds: Array of product IDs to pay royalties for
  • royalties.acceptOffchain(inputs): Accepts off-chain royalty payments (licensor action)
    • inputs: Array of acceptance inputs with product IDs and period ranges
  • royalties.denyOffchain(inputs): Denies off-chain royalty payments (licensor action)
    • inputs: Array of denial inputs with product IDs and period ranges

​
Royalty Workflow

  1. Invoice Generation: Generate or prepare CSV invoice data
  2. Royalty Registration: Register royalties using the CSV data and product IDs
  3. Payment Processing: Licensee initiates off-chain royalty payments
  4. Licensor Review: Licensor can accept or deny royalty payments for specific periods
  5. Job Monitoring: Use utils.pollJobStatus() to monitor all async operations
⌘I