Skip to main content
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

​
new RoyaltyClient()

new RoyaltyClient(publicClient, walletClient, contractAddress): RoyaltyClient

​
Parameters

publicClient
walletClient
contractAddress
`0x${string}`

​
Returns

RoyaltyClient

​
Methods

​
getRoyaltyInfoCount()

getRoyaltyInfoCount(tokenId): Promise<bigint>
Get the number of royalty info periods for a token

​
Parameters

tokenId
bigint The ID of the token to get royalty period count for

​
Returns

Promise<bigint> The number of royalty periods for the token

​
getRoyaltyInfoPeriod()

getRoyaltyInfoPeriod(tokenId, index): Promise<RoyaltyInfoPeriod>
Get royalty info for a specific period

​
Parameters

tokenId
bigint The ID of the token to get royalty period info for
index
bigint The index of the royalty period

​
Returns

Promise<RoyaltyInfoPeriod> Detailed information about the royalty period

​
registerRoyaltyDue()

registerRoyaltyDue(tokenId, amountDue, startDate, endDate, royaltyInfoIndex): Promise<`0x${string}`>
Register royalty due for a period

​
Parameters

tokenId
bigint The ID of the token to register royalty for
amountDue
bigint The amount of royalty due for the period
startDate
bigint The start date of the royalty period (as Unix timestamp)
endDate
bigint The end date of the royalty period (as Unix timestamp)
royaltyInfoIndex
bigint The index of the royalty info

​
Returns

Promise<`0x${string}`> 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.

​
delegatedRegisterRoyaltyDue()

delegatedRegisterRoyaltyDue(tokenId, amountDue, startDate, endDate, royaltyInfoIndex, signature): Promise<`0x${string}`>
Register royalty due for a period on behalf of a third party

​
Parameters

tokenId
bigint The ID of the token to register royalty for
amountDue
bigint The amount of royalty due for the period
startDate
bigint The start date of the royalty period (as Unix timestamp)
endDate
bigint The end date of the royalty period (as Unix timestamp)
royaltyInfoIndex
bigint The index of the royalty info
signature
`0x${string}` Signature authorizing the registration

​
Returns

Promise<`0x${string}`> Transaction hash

​
payRoyalty()

payRoyalty(tokenId, amountPaid, periodIndex, culturaBoundAccount, signature): Promise<`0x${string}`>
Pay royalty for a period

​
Parameters

tokenId
bigint The ID of the token to pay royalty for
amountPaid
bigint The amount of royalty being paid
periodIndex
bigint The index of the royalty period being paid
culturaBoundAccount
`0x${string}` The Cultura bound account address
signature
`0x${string}` Signature authorizing the payment

​
Returns

Promise<`0x${string}`> Transaction hash

​
delegatedPayRoyalty()

delegatedPayRoyalty(tokenId, amountPaid, periodIndex, culturaBoundAccount, signature, delegatedSignature): Promise<`0x${string}`>
Pay royalty for a period on behalf of a third party

​
Parameters

tokenId
bigint The ID of the token to pay royalty for
amountPaid
bigint The amount of royalty being paid
periodIndex
bigint The index of the royalty period being paid
culturaBoundAccount
`0x${string}` The Cultura bound account address
signature
`0x${string}` Signature authorizing the payment
delegatedSignature
`0x${string}` Signature authorizing the payment on behalf of a third party

​
Returns

Promise<`0x${string}`> Transaction hash

​
reportOffChainPayment()

reportOffChainPayment(tokenId, periodIndex, amount, metadata): Promise<`0x${string}`>
Report an off-chain payment for a royalty period

​
Parameters

tokenId
bigint The ID of the token the payment is for
periodIndex
bigint The period index the payment applies to
amount
bigint The amount of the off-chain payment
metadata
string Additional information about the payment

​
Returns

Promise<`0x${string}`> Transaction hash

​
delegatedReportOffChainPayment()

delegatedReportOffChainPayment(tokenId, periodIndex, amount, metadata, signature): Promise<`0x${string}`>
Report an off-chain payment for a royalty period on behalf of a third party

​
Parameters

tokenId
bigint The ID of the token the payment is for
periodIndex
bigint The period index the payment applies to
amount
bigint The amount of the off-chain payment
metadata
string Additional information about the payment
signature
`0x${string}` Signature authorizing the payment

​
Returns

Promise<`0x${string}`> Transaction hash

​
acceptOffChainPaymentByParent()

acceptOffChainPaymentByParent(tokenId, periodIndex, parentBoundAccount, signature, signerAddress, sponsorAddress): Promise<`0x${string}`>
Accept an off-chain payment that was previously reported by a parent.

​
Parameters

tokenId
bigint The ID of the token the payment is for
periodIndex
bigint The period index the payment applies to
parentBoundAccount
`0x${string}` The bound account address of the parent for payment processing
signature
`0x${string}` Signature from the parent’s owner authorizing the acceptance against the parent’s bound account.
signerAddress
`0x${string}` The address of the signer.
sponsorAddress
`0x${string}` The address of the sponsor.

​
Returns

Promise<`0x${string}`> Transaction hash

​
denyOffChainPaymentByParent()

denyOffChainPaymentByParent(tokenId, periodIndex, parentBoundAccount, signature, signerAddress): Promise<`0x${string}`>
Deny an off-chain payment that was previously reported by a parent.

​
Parameters

tokenId
bigint The ID of the token the payment is for
periodIndex
bigint The period index the payment applies to
parentBoundAccount
`0x${string}` The bound account of the parent denying the payment.
signature
`0x${string}` Signature authorizing the denial.
signerAddress
`0x${string}` The address of the signer.

​
Returns

Promise<`0x${string}`> Transaction hash

​
signForAcceptOffChainPaymentByParent()

signForAcceptOffChainPaymentByParent(rightsBoundAccount, totalAmount, period, sponsor): 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.

​
Parameters

rightsBoundAccount
`0x${string}` The address of the parent’s RightsBoundAccount.
totalAmount
bigint The total amount of the payment being accepted.
period
bigint The royalty period index.
sponsor
`0x${string}` The address sponsoring the transaction (usually the parent’s owner).

​
Returns

Promise<`0x${string}`> A promise that resolves to the payment signature.

​
signForDelegatedRegisterRoyaltyDue()

signForDelegatedRegisterRoyaltyDue(tokenId, amountDue, startDate, endDate, royaltyInfoIndex): Promise<`0x${string}`>
Generates a signature for delegated royalty registration This allows a third party to register royalty due on behalf of the signer

​
Parameters

tokenId
bigint The ID of the token to register royalty for
amountDue
bigint The amount of royalty due for the period
startDate
bigint The start date of the royalty period (as Unix timestamp)
endDate
bigint The end date of the royalty period (as Unix timestamp)
royaltyInfoIndex
bigint The index of the royalty info

​
Returns

Promise<`0x${string}`> The signature that can be used for delegated royalty registration

​
signForDelegatedPayRoyalty()

signForDelegatedPayRoyalty(tokenId, amountDue, royaltyInfoIndex): Promise<`0x${string}`>
Generates a signature for delegated royalty payment This allows a third party to pay royalty on behalf of the signer

​
Parameters

tokenId
bigint The ID of the token to pay royalty for
amountDue
bigint The amount of royalty being paid
royaltyInfoIndex
bigint The index of the royalty period being paid

​
Returns

Promise<`0x${string}`> The signature that can be used for delegated royalty payment

​
signForDenyOffChainPaymentByParent()

signForDenyOffChainPaymentByParent(tokenId, periodIndex, parentBoundAccount): Promise<`0x${string}`>
Generates signature for denying an off-chain payment by a parent.

​
Parameters

tokenId
bigint The ID of the token the payment is for
periodIndex
bigint The period index of the royalty payment
parentBoundAccount
`0x${string}` The bound account of the parent denying the payment.

​
Returns

Promise<`0x${string}`> Signature for denying the off-chain payment

​
signForDelegatedOffchainReportRoyalty()

signForDelegatedOffchainReportRoyalty(tokenId, royaltyInfoIndex, amount): 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

​
Parameters

tokenId
bigint The ID of the token to pay royalty for
royaltyInfoIndex
bigint The index of the royalty period being paid
amount
bigint

​
Returns

Promise<`0x${string}`> The signature that can be used for delegated royalty payment

​
signForDelegatedOffchainAcceptRoyalty()

signForDelegatedOffchainAcceptRoyalty(tokenId, royaltyInfoIndex): 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

​
Parameters

tokenId
bigint The ID of the token to accept the off-chain payment for
royaltyInfoIndex
bigint The index of the royalty period being accepted

​
Returns

Promise<`0x${string}`> The signature that can be used for delegated acceptance of an off-chain payment

​
generateSignatureParams()

generateSignatureParams(signature, signerAddress): object
Generates signature parameters required for delegated operations

​
Parameters

signature
`0x${string}` The signed message signature
signerAddress
`0x${string}` The address of the signer

​
Returns

object Signature parameters object with signature, signer, v, r, and s values
signature
signature: `0x${string}`
signer
signer: `0x${string}`
v
v: number
r
r: `0x${string}`
s
s: `0x${string}`

​
getParentAcceptanceInfo()

getParentAcceptanceInfo(tokenId, periodIndex, parentBoundAccount): Promise<ParentAcceptanceInfo>

​
Parameters

tokenId
bigint
periodIndex
bigint
parentBoundAccount
`0x${string}`

​
Returns

Promise<ParentAcceptanceInfo>

​
getOffChainPaymentInfo()

getOffChainPaymentInfo(tokenId, periodIndex): Promise<OffChainPaymentInfo>
Get information about an off-chain payment

​
Parameters

tokenId
bigint The ID of the token to check
periodIndex
bigint The period index to check

​
Returns

Promise<OffChainPaymentInfo> Information about the off-chain payment

​
getAllParentAcceptanceInfo()

getAllParentAcceptanceInfo(tokenId, periodIndex, culturaDigitalAssetAddress): Promise<object[]>
Get all parent acceptance information for an off-chain payment

​
Parameters

tokenId
bigint The ID of the token to check
periodIndex
bigint The period index to check
culturaDigitalAssetAddress
`0x${string}` The address of the Cultura Digital Asset contract

​
Returns

Promise<object[]> Array of parent acceptance info with their bound account addresses

​
getFullRoyaltyInfo()

getFullRoyaltyInfo(tokenId): Promise<RoyaltyInfoPeriod[]>
Get the full royalty information for a token

​
Parameters

tokenId
bigint The ID of the token to get all royalty info for

​
Returns

Promise<RoyaltyInfoPeriod[]> Array of royalty info periods