@cultura/sdk
Version:
SDK for interacting with Cultura, a Layer 2 Ethereum blockchain acting as the global registry for human creativity and IP. It ensures transparent licensing, revenue sharing, and secure provenance.
1,120 lines (1,110 loc) • 708 kB
text/typescript
import * as viem from 'viem';
import { Address, PublicClient, WalletClient, Hex, Transport, Account as Account$1 } from 'viem';
import * as _privy_io_react_auth_smart_wallets from '@privy-io/react-auth/smart-wallets';
import { Client } from '@urql/core';
/**
* Basic types used across the SDK
*/
type TokenAmountInput = bigint | number;
type AttestationData = {
recipient: Address;
expirationTime: bigint;
revocable: boolean;
refUID: `0x${string}`;
data: `0x${string}`;
value?: bigint;
};
type SignatureParams = {
signature: `0x${string}`;
signer: Address;
v: number;
r: `0x${string}`;
s: `0x${string}`;
};
type AttestationRequest = {
schema: `0x${string}`;
data: {
recipient: Address;
expirationTime: bigint;
revocable: boolean;
refUID: `0x${string}`;
data: `0x${string}`;
};
};
type ChallengeRequest = {
attestation: `0x${string}`;
data: AttestationData & {
value: bigint;
};
};
type Attestation = {
uid: `0x${string}`;
schema: `0x${string}`;
time: bigint;
expirationTime: bigint;
revocationTime: bigint;
refUID: `0x${string}`;
recipient: Address;
verifier: Address;
verifierCount: bigint;
revocable: boolean;
data: `0x${string}`;
bondedAmount: bigint;
nftAddress: Address;
nftId: bigint;
};
type SchemaRecord = {
uid: `0x${string}`;
revocable: boolean;
schema: string;
};
type TransactionResponse = {
txHash?: `0x${string}`;
encodedTxData?: `0x${string}`;
};
type AttestationResponse = TransactionResponse & {
attestationId?: `0x${string}`;
};
type ChallengeResponse = TransactionResponse & {
challengeId?: `0x${string}`;
};
/**
* Client for interacting with the Cultura Attestation Service.
*
* The Attestation Service manages the creation and verification of attestations
* that prove digital asset ownership and rights. The attestation process is a crucial
* first step after minting a digital asset, where creators bond tokens to validate their
* ownership claims.
*
* @group Attestation Service
*/
declare class AttestationServiceClient {
private readonly publicClient;
private readonly walletClient;
private readonly contractAddress;
constructor(publicClient: PublicClient, walletClient: WalletClient, contractAddress: `0x${string}`);
/**
* Create an attestation for a digital asset
*
* @param attestationRequest - Object containing attestation details
* @param digitalAssetAddress - Address of the digital asset token contract
* @param digitalAssetId - Token ID of the digital asset being attested
* @param assetClass - Asset class ID for the attestation (affects fees and requirements)
* @param bondAmount - Amount of tokens to bond for the attestation
*
* @returns An object containing the unique identifier (UID) of the created attestation and the address of the deployed Rights Bound Account.
*
* @example
* ```typescript
* const attestationRequest = {
* schema: schemaHash,
* data: {
* recipient: userAddress,
* expirationTime: BigInt(Math.floor(Date.now() / 1000) + 365 * 24 * 60 * 60),
* revocable: true,
* refUID: "0x0000000000000000000000000000000000000000000000000000000000000000",
* data: "0x"
* }
* }
*
* const attestationData = await sdk.attestationService.attest(
* attestationRequest,
* tokenAddress,
* tokenId,
* assetClass,
* bondAmount
* );
* ```
*/
attest(attestationRequest: AttestationRequest, digitalAssetAddress: `0x${string}`, digitalAssetId: bigint, assetClass: bigint, bondAmount: bigint): Promise<{
attestationUid: `0x${string}`;
rightsBoundAccount: `0x${string}`;
}>;
/**
* Create a sponsored attestation for a digital asset paid by a third party
*
* @param attestationRequest - Object containing attestation details
* @param digitalAssetAddress - Address of the digital asset token contract
* @param digitalAssetId - Token ID of the digital asset being attested
* @param assetClass - Asset class ID for the attestation (affects fees and requirements)
* @param bondAmount - Amount of tokens to bond for the attestation
* @param payer - Address of the sponsor/payer
*
* @returns An object containing the unique identifier (UID) of the created attestation and the address of the deployed Rights Bound Account.
*
* @example
* ```typescript
* const attestationRequest = {
* schema: schemaHash,
* data: {
* recipient: userAddress,
* expirationTime: BigInt(Math.floor(Date.now() / 1000) + 365 * 24 * 60 * 60),
* revocable: true,
* refUID: "0x0000000000000000000000000000000000000000000000000000000000000000",
* data: "0x"
* }
* }
*
* const attestationData = await sdk.attestationService.sponsoredAttest(
* attestationRequest,
* tokenAddress,
* tokenId,
* assetClass,
* bondAmount,
* payer
* );
* ```
*/
sponsoredAttest(attestationRequest: AttestationRequest, digitalAssetAddress: `0x${string}`, digitalAssetId: bigint, assetClass: bigint, bondAmount: bigint, payer: `0x${string}`): Promise<{
attestationUid: `0x${string}`;
rightsBoundAccount: `0x${string}`;
}>;
/**
* Create a delegated attestation
*
* This method allows a user to create an attestation on behalf of another account,
* using a signature from that account for authorization.
*
* @param signatureParams - Parameters for the signature verification
* @param attestationRequest - Object containing attestation details
* @param digitalAssetAddress - Address of the digital asset token contract
* @param digitalAssetId - Token ID of the digital asset being attested
* @param assetClass - Asset class ID for the attestation (affects fees and requirements)
* @param bondAmount - Amount of tokens to bond for the attestation
* @param delegatedAddress - Address that will perform the attestation on behalf of the signer
* @returns An object containing the unique identifier (UID) of the created attestation and the address of the deployed Rights Bound Account.
*/
delegatedAttest(signatureParams: SignatureParams, attestationRequest: AttestationRequest, digitalAssetAddress: `0x${string}`, digitalAssetId: bigint, assetClass: bigint, bondAmount: bigint, delegatedAddress: `0x${string}`): Promise<{
attestationUid: `0x${string}`;
rightsBoundAccount: `0x${string}`;
}>;
/**
* Create a delegated attestation
*
* This method allows a user to create an attestation on behalf of another account,
* using a signature from that account for authorization.
*
* @param signatureParams - Parameters for the signature verification
* @param attestationRequest - Object containing attestation details
* @param digitalAssetAddress - Address of the digital asset token contract
* @param digitalAssetId - Token ID of the digital asset being attested
* @param assetClass - Asset class ID for the attestation (affects fees and requirements)
* @param bondAmount - Amount of tokens to bond for the attestation
* @param delegatedAddress - Address that will perform the attestation on behalf of the signer
* @returns An object containing the unique identifier (UID) of the created attestation and the address of the deployed Rights Bound Account.
*/
sponsoredDelegatedAttest(signatureParams: SignatureParams, attestationRequest: AttestationRequest, digitalAssetAddress: `0x${string}`, digitalAssetId: bigint, assetClass: bigint, bondAmount: bigint, delegatedAddress: `0x${string}`, payer: `0x${string}`): Promise<{
attestationUid: `0x${string}`;
rightsBoundAccount: `0x${string}`;
}>;
/**
* Verify an attestation by bonding tokens
*
* This method allows a verifier to stake tokens against an attestation,
* supporting its validity. Verifiers receive rewards for accurate verifications.
*
* A digital asset can achieve Verified Rights status when it meets either of these thresholds:
* 1. Total bonded tokens reach the level requirement
* 2. Number of unique verifiers reaches the minimum threshold
*
* @param attestationUID - Unique identifier of the attestation to verify
* @param bondAmount - Amount of tokens to bond for the verification
* @returns Transaction hash of the verification transaction
*
* @remarks
* Important notes about the Verified Rights promotion process:
* - Only one endorsement per address is counted towards the verifier threshold
* - Endorsement amounts are cumulative for the token threshold
* - Once Verified Rights level 2 is achieved, the digital asset can be used in licensing and other trust-dependent transactions
* - Professional verifiers' endorsements may carry additional weight in the verification process
* - The level system reflects the trust and verification achieved by the digital asset
*
* @example
* ```typescript
* const txHash = await attestationService.verifyAttestation(
* attestationUID,
* ethers.utils.parseEther("10")
* );
* ```
*/
verifyAttestation(attestationUID: `0x${string}`, bondAmount: bigint): Promise<`0x${string}`>;
/**
* Check if an address is a whitelisted verifier
* @param address The address to check
* @returns True if the address is a whitelisted verifier, false otherwise
*/
isWhitelistedVerifier(address: `0x${string}`): Promise<boolean>;
/**
* Add a new whitelisted verifier
* @param verifierAddress The address to add as a whitelisted verifier
* @returns The transaction hash
*/
addWhitelistVerifier(verifierAddress: `0x${string}`): Promise<`0x${string}`>;
/**
* Check if an address is the owner of the contract
* @param address The address to check
* @returns True if the address is the owner, false otherwise
*/
isOwner(address: `0x${string}`): Promise<boolean>;
/**
* Get the current nonce for an address
* @param address The address to get the nonce for
* @returns The current nonce as a bigint
*/
getNonce(address: `0x${string}`): Promise<bigint>;
/**
* Gets the current classId of a digital asset.
*
* The classId is selected by the digital asset minter during attestation and determines
* both the initial bond requirement and the thresholds for verified rights promotion.
*
* @param digitalAssetAddress - Address of the digital asset contract
* @param digitalAssetId - Token ID of the digital asset to check
*
* @remarks
* The classId cannot be changed after attestation and determines the requirements for verified rights level.
* Currently, there is one asset class defined, with each class having its own specific requirements
* for initial bonds, verification thresholds, and trust factors in the verification process.
*
* @group Attestation Service
*/
getDigitalAssetClassId(digitalAssetAddress: `0x${string}`, digitalAssetId: bigint): Promise<number>;
/**
* Get the level of a digital asset
* @param digitalAssetAddress The address of the digital asset contract
* @param digitalAssetId The token ID of the digital asset
* @returns The level of the digital asset (0 = unverified, 1 = basic, 2 = verified/licensable)
*
* @remarks
* The level system represents the verification status of a digital asset:
* - Level 0: Just minted - Initial state of any newly minted digital asset
* - Level 1: Attested - Digital asset creator has completed attestation, initial bond and fee paid
* - Level 2: Verified Rights - Achieved through community endorsements, meets token threshold or unique verifiers requirement
*
* Important Notes:
* - All digital assets, regardless of classId, can achieve Verified Rights status
* - Verified Rights level 2 is required for licensing and other trust-dependent operations
* - Level status is independent of the digital asset's classId
*
* @example
* ```typescript
* const level = await sdk.attestationService.getDigitalAssetLevel(digitalAssetAddress, tokenId);
* console.log('Digital Asset Level Status:',
* level === 0 ? 'Just Minted' :
* level === 1 ? 'Attested' :
* level === 2 ? 'Verified Rights (Licensable)' : 'Unknown'
* );
* ```
*/
getDigitalAssetLevel(digitalAssetAddress: `0x${string}`, digitalAssetId: bigint): Promise<number>;
/**
* Remove a whitelisted verifier
* @param verifierAddress The address to remove from the whitelist
* @returns The transaction hash
*/
removeWhitelistedVerifier(verifierAddress: `0x${string}`): Promise<`0x${string}`>;
/**
* Retrieves detailed information about an attestation by its unique identifier.
*
* Use this method to get complete information about a specific attestation,
* including the recipient, verifier, schema reference, and associated data.
*
* @param uid - Unique identifier of the attestation to retrieve
*
* @returns Complete attestation data including recipient, verifier, schema, digital asset details, and bond amounts
*
* @example
* ```typescript
* const attestation = await sdk.attestationService.getAttestation(attestationUID);
* console.log('Attestation details:', attestation);
* ```
*
* @group Attestation Service
*/
getAttestation(uid: `0x${string}`): Promise<{
uid: `0x${string}`;
schema: `0x${string}`;
time: bigint;
expirationTime: bigint;
revocationTime: bigint;
refUID: `0x${string}`;
recipient: `0x${string}`;
attester: `0x${string}`;
verifierCount: bigint;
revocable: boolean;
data: `0x${string}`;
bondedAmount: bigint;
digitalAssetAddress: `0x${string}`;
digitalAssetId: bigint;
communityUserCount: bigint;
WLVerifierCount: bigint;
}>;
/**
* Extracts the rights bound account from a transaction receipt.
*
* @param receipt - The transaction receipt to extract the rights bound account from
* @returns The rights bound account address if found, zero address otherwise
*/
getRightsBoundAccountFromReceipt(receipt: {
logs: {
data: `0x${string}`;
topics: readonly `0x${string}`[];
}[];
}): `0x${string}`;
/**
* Extracts attestation data from a transaction receipt.
*
* @param receipt - The transaction receipt to extract the attestation data from
* @returns The attestation data including UID and rights bound account
* @throws Error if the attestation UID is not found in the logs
*/
getAttestationDataFromReceipt(receipt: {
logs: {
data: `0x${string}`;
topics: readonly `0x${string}`[];
}[];
}): {
attestationUid: `0x${string}`;
rightsBoundAccount: `0x${string}`;
};
/**
* Get the rights bound account address for a digital asset
* @param digitalAssetAddress The address of the digital asset contract
* @param digitalAssetId The token ID of the digital asset
* @returns The address of the rights bound account for the digital asset
*
* @remarks
* This method queries the CAS contract's digitalAssetBoundAccounts mapping to retrieve
* the rights bound account address that was deployed during the attestation process.
*
* @example
* ```typescript
* const rightsBoundAccountAddress = await sdk.attestationService.getRightsBoundAccountAddress(
* digitalAssetAddress,
* tokenId
* );
* ```
*/
getRightsBoundAccountAddress(digitalAssetAddress: `0x${string}`, digitalAssetId: bigint): Promise<`0x${string}`>;
/**
* Generates signature parameters required for delegated attestation
*
* @param signature - The signed message signature
* @param signerAddress - The address of the signer
* @returns Signature parameters object with signature, signer, v, r, and s values
*/
generateSignatureParams(signature: `0x${string}`, signerAddress: `0x${string}`): {
signature: `0x${string}`;
signer: `0x${string}`;
v: number;
r: `0x${string}`;
s: `0x${string}`;
};
/**
* Signs a message for delegated attestation and returns the signature parameters
*
* @param account - The account performing the signature
* @returns Signature parameters object with signature, signer, v, r, and s values
*/
signForDelegatedAttestation(account: `0x${string}`): Promise<{
signature: `0x${string}`;
signer: `0x${string}`;
v: number;
r: `0x${string}`;
s: `0x${string}`;
}>;
/**
* Generates multiple signatures for delegated attestations in bulk.
* This is useful when you need to sign for several attestations upfront,
* as each signature will use an incrementing nonce starting from the signer's current nonce.
*
* @param account - The account performing the signatures.
* @param numberOfSignatures - The total number of signatures to generate.
* @returns A promise that resolves to an array of signature parameters objects.
* Each object contains the signature, signer, v, r, and s values.
* These signatures must be used in the order they are returned,
* as they correspond to sequential nonces.
* @throws Error if the wallet client is not available or if numberOfSignatures is not positive.
*/
signForBulkDelegatedAttestations(account: `0x${string}`, numberOfSignatures: number): Promise<Array<{
signature: `0x${string}`;
signer: `0x${string}`;
v: number;
r: `0x${string}`;
s: `0x${string}`;
}>>;
}
/**
* Client for interacting with the Schema Registry contract
*
* The Schema Registry contract is used to register and manage the schemas for digital asset attestations.
* It provides a method to register a new schema or get the hash of an existing schema.
*
* @group Schema Registry
*/
declare class SchemaRegistryClient {
private readonly publicClient;
private readonly walletClient;
private readonly contractAddress;
constructor(publicClient: PublicClient, walletClient: WalletClient, contractAddress: `0x${string}`);
/**
* Register a new schema
* @param schema The schema string to register
* @param revocable Whether attestations using this schema can be revoked
* @returns The schema UID (hash)
*/
register(schema: string, revocable: boolean): Promise<`0x${string}`>;
/**
* Get schema by UID
* @param uid The unique identifier (hash) of the schema
* @returns The schema data including the schema string and revocable flag
*/
getSchema(uid: `0x${string}`): Promise<{
uid: `0x${string}`;
revocable: boolean;
schema: string;
}>;
/**
* Check if a schema is revocable
* @param uid The unique identifier (hash) of the schema
* @returns Boolean indicating if attestations using this schema can be revoked
*/
isRevocable(uid: `0x${string}`): Promise<boolean>;
/**
* Calculate schema hash using the same method as the contract
* @param schema The schema string
* @param revocable Whether the schema is revocable
* @returns The calculated schema hash
*/
private calculateSchemaHash;
/**
* Register a new schema or get existing schema hash
* @param schema The schema string to register
* @param revocable Whether the schema is revocable
* @returns The schema hash
*
* @remarks
* This function is fundamental to the attestation process as it:
* 1. Defines the data structure for digital asset attestations
* 2. Ensures consistency in how digital asset data is stored and verified
* 3. Controls whether attestations can be revoked
*
* Schema Structure:
* The schema string follows Solidity's parameter encoding format and typically includes:
* - `digitalAssetName`: Name of the digital asset
* - `digitalAssetDescription`: Detailed description of the digital asset
* - `grade`: Numerical grade/rating of the digital asset
*
* @example
* ```typescript
* // Define a schema for digital asset attestations
* const schemaStr = 'string digitalAssetName, string digitalAssetDescription, uint256 grade';
* const isRevocable = true;
*
* // Register or get the schema
* const schemaHash = await sdk.schemaRegistry.getOrRegisterSchema(schemaStr, isRevocable);
* ```
*/
getOrRegisterSchema(schema: string, revocable: boolean): Promise<`0x${string}`>;
}
/**
* Represents a parent digital asset for inheritance tracking
*/
type RoyaltyPayeesInfo = Readonly<{
rightsBoundAccount: `0x${string}`;
/** Royalty split allocated to this parent, expressed as a whole number percentage (e.g., 10 for 10%). */
royaltySplit: bigint;
payeeType: `0x${string}`;
agents: AgentPlan$1[];
}>;
type AgentPlan$1 = Readonly<{
agentAddress: `0x${string}`;
agentAmountBps: bigint;
agentFeeBps: bigint;
}>;
/**
* Represents the complete license information for a digital asset token
*/
type LicenseInfo = Readonly<{
digitalAssetName: string;
digitalAssetDescription: string;
creator: `0x${string}`;
royaltyPayeesInfo: readonly RoyaltyPayeesInfo[];
termsURI: string;
}>;
/**
* Client for interacting with the CulturaDigitalAsset NFT contract
*
* Functions for managing Cultura Digital Assets (implemented as ERC721 tokens with extended licensing capabilities)
*
* @group Cultura Digital Asset
*/
declare class CulturaDigitalAssetClient {
private readonly publicClient;
private readonly walletClient;
private readonly contractAddress;
constructor(publicClient: PublicClient, walletClient: WalletClient, contractAddress: `0x${string}`);
/**
* Mints a new digital asset token with specified metadata (Script version using low-level transaction handling)
* @param to Address that will receive the minted token
* @param digitalAssetName Name of the digital asset
* @param digitalAssetDescription Description of the digital asset
* @param royaltyPayeesInfo Array of parent digital asset information for derivative works
* @param termsURI URI pointing to the detailed terms of the digital asset
* @param tokenURI Token URI for the ERC-721 metadata
* @returns The ID of the newly minted token
* @private
*/
private _safeMint;
/**
* Mints a new digital asset token with specified metadata (React version using high-level contract interaction)
* @param to Address that will receive the minted token
* @param digitalAssetName Name of the digital asset
* @param digitalAssetDescription Description of the digital asset
* @param royaltyPayeesInfo Array of parent digital asset information for derivative works
* @param terms Terms for the digital asset - can be a JSON object (to be uploaded to IPFS) or a string URI (pre-hosted)
* @param tokenURI Token URI for the ERC-721 metadata - can be a JSON object (to be uploaded to IPFS) or a string URI (pre-hosted)
* @returns The ID of the newly minted token
*
* @remarks
* This method mints a new digital asset token with licensing information. For derivative works,
* the royaltyPayeesInfo array should contain:
* - rightsBoundAccount: Address of parent digital asset collection (0x0 for original asset)
* - digitalAssetClass: Token ID of parent digital asset (0 for original asset)
* - royaltySplit: Percentage of royalties allocated to parent digital asset, expressed as a whole number (e.g., 10 for 10%).
*
* **Important:** The sum of `royaltySplit` values across all `royaltyPayeesInfo` must equal exactly 75.
* (Note: This 75% value is currently hardcoded in the contract and may change in future versions).
*/
mintDigitalAsset(to: `0x${string}`, digitalAssetName: string, digitalAssetDescription: string, royaltyPayeesInfo: readonly RoyaltyPayeesInfo[], terms: Record<string, any> | string, tokenURI: Record<string, any> | string): Promise<bigint>;
/**
* Gets the complete license information for a token
* @param tokenId The identifier of the token
* @returns Complete license information including name, description, creator, parent Digital Assets, and terms URI
*
* @remarks
* Returns a complete object containing:
* ```typescript
* {
* digitalAssetName: string
* digitalAssetDescription: string
* creator: address
* royaltyPayeesInfo: RoyaltyPayeesInfo[]
* termsURI: string
* }
* ```
*/
getLicenseInfo(tokenId: bigint): Promise<LicenseInfo>;
/**
* Get token owner
*/
ownerOf(tokenId: bigint): Promise<`0x${string}`>;
/**
* Get token URI
*/
tokenURI(tokenId: bigint): Promise<string>;
/**
* Approve an address to transfer a token
*/
approve(to: `0x${string}`, tokenId: bigint): Promise<`0x${string}`>;
/**
* Set approval for all tokens
*/
setApprovalForAll(operator: `0x${string}`, approved: boolean): Promise<`0x${string}`>;
/**
* Get the total supply of tokens
* @returns The total supply as a BigInt
*/
totalSupply(): Promise<bigint>;
/**
* Get a token by its index
* @param index The index of the token
* @returns Token ID at the specified index
*/
tokenByIndex(index: bigint): Promise<bigint>;
}
/**
* Client for interacting with the Cultura Rights Bound Account contract
* Handles payment distributions, royalty claims, and account management
*
* These accounts manage digital asset-related functions and handle royalty distributions to various
* stakeholders including verifiers, Cultura Treasury, and parent digital asset owners.
* They are automatically deployed during the attestation process.
*
* @group Rights Bound Account
*/
declare class RightsBoundAccountClient {
private readonly publicClient;
private readonly walletClient;
private readonly contractAddress;
constructor(publicClient: PublicClient, walletClient: WalletClient, contractAddress: `0x${string}`);
getContractAddress(): `0x${string}`;
/**
* Claim rewards for a period
* @param period The period to claim rewards for
* @returns Transaction hash
*
* @remarks
* Allows stakeholders to claim their share of royalties for a specific period.
*
* @example
* ```typescript
* // Stakeholders can claim their share
* await rightsBoundAccount.claim(currentPeriod);
* ```
*/
claim(period: bigint): Promise<`0x${string}`>;
/**
* Claim from a child bound account
* @param childBoundAccount The address of the child bound account to claim from (the derivative bound account)
* @param period The period to claim for
* @returns Transaction hash
*
* @remarks
* This function allows a parent bound account to claim its allocated share from a downstream
* (child) bound account. This is part of the hierarchical royalty distribution system where
* VR (child) bound accounts distribute payments to their parent bound accounts.
* Important Notes:
* - Cannot override fixed distributions to:
* - Verifier module (for verifiers who helped achieve Verified Rights status)
* - Cultura Treasury
* - Used by protocols to define custom royalty distribution logic
* - Must include parent digital asset owners if the digital asset is a derivative work
*
* @example
* ```typescript
* // Parent bound account claims from VR bound account
* await parentBoundAccount.claimFromChild(vrBoundAccountAddress, period);
* ```
*/
claimFromChild(childBoundAccount: `0x${string}`, period: bigint): Promise<`0x${string}`>;
/**
* Set payment info for a period. This function is used to distribute royalties.
*
* @remarks
* The new simplified flow automatically calculates splits for parents, the Cultura Treasury,
* and the verifier module based on the total amount.
*
* @param info Payment information including total amount, sponsor, and authorization signature.
* @returns Transaction hash
*/
setPaymentInfo(info: {
totalAmount: bigint;
sponsor: `0x${string}`;
signature: `0x${string}`;
signer: `0x${string}`;
}): Promise<`0x${string}`>;
/**
* Generates a signature for setting payment info on a RightsBoundAccount.
*
* @param period - The period index of the royalty payment.
* @param totalAmount - The total amount of the payment.
* @param sponsor - The address that will sponsor the token transfer.
* @returns Signature for setting the payment info.
*/
signForSetPaymentInfo(period: bigint, totalAmount: bigint, sponsor: `0x${string}`): Promise<`0x${string}`>;
/**
* Get current period
* @returns The current period as a bigint
*/
getCurrentPeriod(): Promise<bigint>;
/**
* Get payment amount for a beneficiary in a specific period
* This can be used to determine if a royalty has been claimed
* @param period The payment period
* @param beneficiary The address of the beneficiary
* @returns The payment amount for the beneficiary in the specified period
*/
getPaymentAmount(period: bigint, beneficiary: `0x${string}`): Promise<bigint>;
/**
* Get rights bound account asset address and token id
* @returns The address of the parent bound account
*/
getRightsBoundAccountAsset(): Promise<{
assetAddress: `0x${string}`;
tokenId: bigint;
}>;
}
type ParentPlan = {
parentAddress: `0x${string}`;
parentAmountGross: bigint;
agents: AgentPlan[];
};
type AgentPlan = {
agentAddress: `0x${string}`;
agentAmountBps: bigint;
agentFeeBps: bigint;
};
type RoyaltyInfoPeriod = {
periodStart: bigint;
periodEnd: bigint;
amountDue: bigint;
amountPaid: bigint;
parentPendingClaims: bigint[];
};
/**
* Enum for tracking the status of off-chain payments
*/
declare enum OffChainPaymentStatus {
NONE = 0,
PENDING = 1,
ACCEPTED = 2,
DENIED = 3
}
/**
* Struct representing individual parent acceptance information
*/
type ParentAcceptanceInfo = {
allocatedAmount: bigint;
status: OffChainPaymentStatus;
signature: `0x${string}`;
timestamp: bigint;
};
/**
* Struct representing off-chain payment details for a specific period (internal state)
*/
type OffChainPaymentInfo = {
reportedAmount: bigint;
metadata: string;
reporter: `0x${string}`;
};
/**
* Client for interacting with the Cultura Royalty System contract
*
* This client provides a reference implementation for managing and calculating royalty
* distributions in the Cultura ecosystem. This module can be customized or replaced
* to accommodate different royalty calculation needs.
*
* @remarks
* Protocols can:
* 1. Use this implementation as-is for basic royalty management
* 2. Extend it with additional calculation logic
* 3. Create their own royalty module with custom distribution rules
* 4. Skip the royalty module entirely and interact directly with Rights Bound Accounts
*/
declare class RoyaltyClient {
private readonly publicClient;
private readonly walletClient;
private readonly contractAddress;
constructor(publicClient: PublicClient, walletClient: WalletClient, contractAddress: `0x${string}`);
/**
* Get the number of royalty info periods for a token
* @param tokenId The ID of the token to get royalty period count for
* @returns The number of royalty periods for the token
*/
getRoyaltyInfoCount(tokenId: bigint): Promise<bigint>;
/**
* Get royalty info for a specific period
* @param tokenId The ID of the token to get royalty period info for
* @param index The index of the royalty period
* @returns Detailed information about the royalty period
*/
getRoyaltyInfoPeriod(tokenId: bigint, index: bigint): Promise<RoyaltyInfoPeriod>;
/**
* Register royalty due for a period
* @param tokenId The ID of the token to register royalty for
* @param amountDue The amount of royalty due for the period
* @param startDate The start date of the royalty period (as Unix timestamp)
* @param endDate The end date of the royalty period (as Unix timestamp)
* @param royaltyInfoIndex The index of the royalty info
* @returns Transaction hash
*
* @remarks
* This is an optional step that protocols can use for tracking and transparency.
* This function is part of the reference implementation and can be skipped if
* protocols have their own royalty calculation mechanisms.
*/
registerRoyaltyDue(tokenId: bigint, amountDue: bigint, startDate: bigint, endDate: bigint, royaltyInfoIndex: bigint): Promise<`0x${string}`>;
/**
* Register royalty due for a period on behalf of a third party
* @param tokenId The ID of the token to register royalty for
* @param amountDue The amount of royalty due for the period
* @param startDate The start date of the royalty period (as Unix timestamp)
* @param endDate The end date of the royalty period (as Unix timestamp)
* @param royaltyInfoIndex The index of the royalty info
* @param signature Signature authorizing the registration
* @returns Transaction hash
*
*/
delegatedRegisterRoyaltyDue(tokenId: bigint, amountDue: bigint, startDate: bigint, endDate: bigint, royaltyInfoIndex: bigint, signature: `0x${string}`): Promise<`0x${string}`>;
/**
* Pay royalty for a period
* @param tokenId The ID of the token to pay royalty for
* @param amountPaid The amount of royalty being paid
* @param periodIndex The index of the royalty period being paid
* @param culturaBoundAccount The Cultura bound account address
* @param signature Signature authorizing the payment
* @returns Transaction hash
*
*/
payRoyalty(tokenId: bigint, amountPaid: bigint, periodIndex: bigint, culturaBoundAccount: `0x${string}`, signature: `0x${string}`): Promise<`0x${string}`>;
/**
* Pay royalty for a period on behalf of a third party
* @param tokenId The ID of the token to pay royalty for
* @param amountPaid The amount of royalty being paid
* @param periodIndex The index of the royalty period being paid
* @param culturaBoundAccount The Cultura bound account address
* @param signature Signature authorizing the payment
* @param delegatedSignature Signature authorizing the payment on behalf of a third party
* @returns Transaction hash
*
*/
delegatedPayRoyalty(tokenId: bigint, amountPaid: bigint, periodIndex: bigint, culturaBoundAccount: `0x${string}`, signature: `0x${string}`, delegatedSignature: `0x${string}`): Promise<`0x${string}`>;
/**
* Pay royalty for a period
* @param tokenId The ID of the token to pay royalty for
* @param amountPaid The amount of royalty being paid
* @param periodIndex The index of the royalty period being paid
* @param culturaBoundAccount The Cultura bound account address
* @param signature Signature authorizing the payment
* @returns Transaction hash
*
*/
payRoyaltyWithOffChainSplits(tokenId: bigint, amountPaid: bigint, periodIndex: bigint, culturaBoundAccount: `0x${string}`, signature: `0x${string}`, parentPlans: ParentPlan[]): Promise<`0x${string}`>;
/**
* Pay royalty for a period on behalf of a third party with off-chain splits
* @param tokenId The ID of the token to pay royalty for
* @param amountPaid The amount of royalty being paid
* @param periodIndex The index of the royalty period being paid
* @param culturaBoundAccount The Cultura bound account address
* @param signature Signature authorizing the payment
* @param delegatedSignature Signature authorizing the payment on behalf of a third party
* @param parentAddresses Array of parent addresses for off-chain splits
* @param parentAmounts Array of amounts for each parent
* @returns Transaction hash
*
*/
delegatedPayRoyaltyWithOffChainSplits(tokenId: bigint, amountPaid: bigint, periodIndex: bigint, culturaBoundAccount: `0x${string}`, signature: `0x${string}`, delegatedSignature: `0x${string}`, parentPlans: ParentPlan[]): Promise<`0x${string}`>;
/**
* Report an off-chain payment for a royalty period
* @param tokenId The ID of the token the payment is for
* @param periodIndex The period index the payment applies to
* @param amount The amount of the off-chain payment
* @param metadata Additional information about the payment
* @returns Transaction hash
*/
reportOffChainPayment(tokenId: bigint, periodIndex: bigint, amount: bigint, metadata: string): Promise<`0x${string}`>;
/**
* Report an off-chain payment for a royalty period
* @param tokenId The ID of the token the payment is for
* @param periodIndex The period index the payment applies to
* @param amount The amount of the off-chain payment
* @param metadata Additional information about the payment
* @param parentAddresses Array of parent addresses for off-chain splits
* @param parentAmounts Array of amounts for each parent
* @returns Transaction hash
*/
reportOffChainPaymentWithSplits(tokenId: bigint, periodIndex: bigint, amount: bigint, metadata: string, parentPlans: ParentPlan[]): Promise<`0x${string}`>;
/**
* Report an off-chain payment for a royalty period on behalf of a third party
* @param tokenId The ID of the token the payment is for
* @param periodIndex The period index the payment applies to
* @param amount The amount of the off-chain payment
* @param metadata Additional information about the payment
* @param signature Signature authorizing the payment
* @returns Transaction hash
*/
delegatedReportOffChainPayment(tokenId: bigint, periodIndex: bigint, amount: bigint, metadata: string, signature: `0x${string}`): Promise<`0x${string}`>;
/**
* Report an off-chain payment for a royalty period on behalf of a third party
* @param tokenId The ID of the token the payment is for
* @param periodIndex The period index the payment applies to
* @param amount The amount of the off-chain payment
* @param metadata Additional information about the payment
* @param signature Signature authorizing the payment
* @param parentAddresses Array of parent addresses for off-chain splits
* @param parentAmounts Array of amounts for each parent
* @returns Transaction hash
*/
delegatedReportOffChainPaymentWithSplits(tokenId: bigint, periodIndex: bigint, amount: bigint, metadata: string, signature: `0x${string}`, parentPlans: ParentPlan[]): Promise<`0x${string}`>;
/**
* Accept an off-chain payment that was previously reported by a parent.
* @param tokenId The ID of the token the payment is for
* @param periodIndex The period index the payment applies to
* @param parentBoundAccount The bound account address of the parent for payment processing
* @param signature Signature from the parent's owner authorizing the acceptance against the parent's bound account.
* @param signerAddress The address of the signer.
* @param sponsorAddress The address of the sponsor.
* @returns Transaction hash
*/
claimFeesOffChainPaymentByParent(tokenId: bigint, periodIndex: bigint, parentBoundAccount: `0x${string}`, signature: `0x${string}`, signerAddress: `0x${string}`, sponsorAddress: `0x${string}`): Promise<`0x${string}`>;
/**
* Accept an off-chain payment that was previously reported by a parent.
* @param tokenId The ID of the token the payment is for
* @param periodIndex The period index the payment applies to
* @param parentBoundAccount The bound account address of the parent for payment processing
* @param signature Signature from the parent's owner authorizing the acceptance against the parent's bound account.
* @param signerAddress The address of the signer.
* @param sponsorAddress The address of the sponsor.
* @returns Transaction hash
*/
claimFeesOffChainPaymentByParentWithSplits(tokenId: bigint, periodIndex: bigint, parentBoundAccount: `0x${string}`, signature: `0x${string}`, signerAddress: `0x${string}`, sponsorAddress: `0x${string}`, parentPlan: ParentPlan): Promise<`0x${string}`>;
/**
* Deny an off-chain payment that was previously reported by a parent.
* @param tokenId The ID of the token the payment is for
* @param periodIndex The period index the payment applies to
* @param parentBoundAccount The bound account of the parent denying the payment.
* @param signature Signature authorizing the denial.
* @param signerAddress The address of the signer.
* @returns Transaction hash
*/
denyOffChainPaymentByParent(tokenId: bigint, periodIndex: bigint, parentBoundAccount: `0x${string}`, signature: `0x${string}`, signerAddress: `0x${string}`): Promise<`0x${string}`>;
/**
* Create a signature for an off-chain payment acceptance by a parent.
* The signature is created for the `CulturaRightsBoundAccount` of the parent.
* @param rightsBoundAccount The address of the parent's RightsBoundAccount.
* @param totalAmount The total amount of the payment being accepted.
* @param period The royalty period index.
* @param sponsor The address sponsoring the transaction (usually the parent's owner).
* @param chainId Optional chain ID for the signature domain.
* @returns A promise that resolves to the payment signature.
*/
signForclaimFeesOffChainPaymentByParent(rightsBoundAccount: `0x${string}`, totalAmount: bigint, period: bigint, sponsor: `0x${string}`): Promise<`0x${string}`>;
/**
* Generates a signature for delegated royalty registration
* This allows a third party to register royalty due on behalf of the signer
*
* @param tokenId - The ID of the token to register royalty for
* @param amountDue - The amount of royalty due for the period
* @param startDate - The start date of the royalty period (as Unix timestamp)
* @param endDate - The end date of the royalty period (as Unix timestamp)
* @param royaltyInfoIndex - The index of the royalty info
* @returns The signature that can be used for delegated royalty registration
*/
signForDelegatedRegisterRoyaltyDue(tokenId: bigint, amountDue: bigint, startDate: bigint, endDate: bigint, royaltyInfoIndex: bigint): Promise<`0x${string}`>;
/**
* Generates a signature for delegated royalty payment
* This allows a third party to pay royalty on behalf of the signer
*
* @param tokenId - The ID of the token to pay royalty for
* @param amountDue - The amount of royalty being paid
* @param royaltyInfoIndex - The index of the royalty period being paid
* @returns The signature that can be used for delegated royalty payment
*/
signForDelegatedPayRoyalty(tokenId: bigint, amountDue: bigint, royaltyInfoIndex: bigint): Promise<`0x${string}`>;
/**
* Generates signature for denying an off-chain payment by a parent.
*
* @param tokenId - The ID of the token the payment is for
* @param periodIndex - The period index of the royalty payment
* @param parentBoundAccount - The bound account of the parent denying the payment.
* @returns Signature for denying the off-chain payment
*/
signForDenyOffChainPaymentByParent(tokenId: bigint, periodIndex: bigint, parentBoundAccount: `0x${string}`): Promise<`0x${string}`>;
/**
* Generates a signature for delegated off-chain royalty payment
* This allows a third party to pay royalty on behalf of the signer
*
* @param tokenId - The ID of the token to pay royalty for
* @param amountDue - The amount of royalty being paid
* @param royaltyInfoIndex - The index of the royalty period being paid
* @returns The signature that can be used for delegated royalty payment
*/
signForDelegatedOffchainReportRoyalty(tokenId: bigint, royaltyInfoIndex: bigint, amount: bigint): Promise<`0x${string}`>;
/**
* Generates a signature for delegated off-chain royalty payment
* This allows a third party to pay royalty on behalf of the signer
*
* @param tokenId - The ID of the token to pay royalty for
* @param amountDue - The amount of royalty being paid
* @param royaltyInfoIndex - The index of the royalty period being paid
* @returns The signature that can be used for delegated royalty payment
*/
signForDelegatedOffchainReportRoyaltyWithSplits(tokenId: bigint, royaltyInfoIndex: bigint, amount: bigint): Promise<`0x${string}`>;
/**
* Generates a signature for delegated acceptance of an off-chain payment
* This allows a third party to accept an off-chain payment on behalf of the signer
*
* @param tokenId - The ID of the token to accept the off-chain payment for
* @param royaltyInfoIndex - The index of the royalty period being accepted
* @returns The signature that can be used for delegated acceptance of an off-chain payment
*/
signForDelegatedOffchainAcceptRoyalty(tokenId: bigint, royaltyInfoIndex: bigint): Promise<`0x${string}`>;
/**
* Generates signature parameters required for delegated operations
*
* @param signature - The signed message signature
* @param signerAddress - The address of the signer
* @returns Signature parameters object with signature, signer, v, r, and s values
*/
generateSignatureParams(signature: `0x${string}`, signerAddress: `0x${string}`): {
signature: `0x${string}`;
signer: `0x${string}`;
v: number;
r: `0x${string}`;
s: `0x${string}`;
};
getParentClaimFeePaymentInfo(tokenId: bigint, periodIndex: bigint, parentBoundAccount: `0x${string}`): Promise<ParentAcceptanceInfo>;
/**
* Get information about an off-chain payment
* @param tokenId The ID of the token to check
* @param periodIndex The period index to check
* @returns Information about the off-chain payment
*/
getOffChainPaymentInfo(tokenId: bigint, periodIndex: bigint): Promise<OffChainPaymentInfo>;
/**
* Get all parent acceptance information for an off-chain payment
* @param tokenId The ID of the token to check
* @param periodIndex The period index to check
* @param culturaDigitalAssetAddress The address of the Cultura Digital Asset contract
* @returns Array of parent acceptance info with their bound account addresses
*/
getAllParentAcceptanceInfo(tokenId: bigint, periodIndex: bigint, culturaDigitalAssetAddress: `0x${string}`): Promise<Array<{
parentBoundAccount: `0x${string}`;
acceptanceInfo: ParentAcceptanceInfo;
}>>;
/**
* Get the full royalty information for a token
* @param tokenId The ID of the token to get all royalty info for
* @returns Array of royalty info periods
*/
getFullRoyaltyInfo(tokenId: bigint): Promise<Array<RoyaltyInfoPeriod>>;
}
/**
* Client for interacting with the SignatureUtils contract
*
* @group Signature Utils
*/
declare class SignatureUtilsClient {
private readonly publicClient;
private readonly contractAddress;
constructor(publicClient: PublicClient, contractAddress: `0x${string}`);
/**
* Get the delegated self attest typehash
*/
getDelegatedSelfAttestTypeHash(): Promise<Hex>;
}
/**
* Client for interacting with the Bond Token (ERC20) contract
*
* Provides an interface for interacting with ERC20 tokens used for bonding in self-attestations
* and other platform functions. This client handles token operations like approvals and balance checks,
* with a test-only minting function.
*
* @remarks
* Token approvals are required before any operation that needs to transfer tokens
* (self-attestation, endorsements, etc.)
*
* @group Bond Token
*/
declare class BondTokenClient {
private readonly publicClient;
private readonly walletClient;
private readonly contractAddress;
constructor(publicClient: PublicClient, walletClient: WalletClient, contractAddress: `0x${string}`);
/**
* Mints new bond tokens to a specified account (only for testing)
* @param account Address that will receive the minted tokens
* @param amount Amount of tokens to mint
* @returns Transaction hash
*
* @remarks
* This function is only available on test networks. In production/mainnet,
* tokens must be acquired through proper channels (exchanges, transfers, etc).
*/
mint(account: `0x${string}`, amount: bigint): Promise<`0x${string}`>;
/**
* Approves an address to spend tokens on behalf of the caller
* @param spender Address that will be approved to spend tokens
* @param amount Amount of tokens to approve
* @returns Transaction hash