From f07cec38665569003517c31f1e536b43a9a62966 Mon Sep 17 00:00:00 2001 From: Don <100505855+DonFungible@users.noreply.github.com> Date: Sat, 17 Feb 2024 14:56:25 -0800 Subject: [PATCH] add more comments --- packages/core-sdk/src/resources/dispute.ts | 8 ++--- packages/core-sdk/src/resources/ipAsset.ts | 36 ++++++++++++++----- packages/core-sdk/src/resources/license.ts | 12 +++++++ packages/core-sdk/src/resources/permission.ts | 25 +++++++++---- .../src/types/resources/permission.ts | 6 ++-- 5 files changed, 66 insertions(+), 21 deletions(-) diff --git a/packages/core-sdk/src/resources/dispute.ts b/packages/core-sdk/src/resources/dispute.ts index 89153821..64f6f079 100644 --- a/packages/core-sdk/src/resources/dispute.ts +++ b/packages/core-sdk/src/resources/dispute.ts @@ -24,7 +24,7 @@ export class DisputeClient { } /** - * Initiates a dispute on an IP. + * Raises a dispute on a given ipId * @param request - The request object containing necessary data to raise a dispute. * @param request.targetIpId - The IP ID that is the target of the dispute. * @param request.arbitrationPolicy - The address of the arbitration policy. @@ -71,7 +71,7 @@ export class DisputeClient { } /** - * Sets the judgement for an existing dispute. + * Sets the dispute judgement on a given dispute. Only whitelisted arbitration relayers can call to judge. * @param request The request object containing details for setting the dispute judgement. * @param request.disputeId The ID of the dispute to be judged. * @param request.decision The decision of the dispute. @@ -111,7 +111,7 @@ export class DisputeClient { } /** - * Cancels an existing dispute. + * Cancels an ongoing dispute * @param request The request object containing details to cancel the dispute. * @param request.disputeId The ID of the dispute to be cancelled. * @param request.calldata Optional additional data used in the cancellation process. @@ -143,7 +143,7 @@ export class DisputeClient { } /** - * Resolves an existing dispute after a judgement has been set. + * Resolves a dispute after it has been judged * @param request The request object containing details to resolve the dispute. * @param request.disputeId The ID of the dispute to be resolved. * @returns A Promise that resolves to a ResolveDisputeResponse. diff --git a/packages/core-sdk/src/resources/ipAsset.ts b/packages/core-sdk/src/resources/ipAsset.ts index ded5964b..4b3ff027 100644 --- a/packages/core-sdk/src/resources/ipAsset.ts +++ b/packages/core-sdk/src/resources/ipAsset.ts @@ -21,10 +21,20 @@ export class IPAssetClient { } /** - * Register a root IP on Story Protocol based on the specified input asset data. - * - * @param request - the request object that contains all data needed to register a root IP. - * @returns the response object that contains results from the IP creation. + * Registers a root-level IP into the protocol. Root-level IPs can be thought of as organizational hubs + * for encapsulating policies that actual IPs can use to register through. As such, a root-level IP is not an + * actual IP, but a container for IP policy management for their child IP assets. + * @param request The request object that contains all data needed to register a root IP. + * @param request.policyId The policy that identifies the licensing terms of the IP. + * @param request.tokenContract The address of the NFT bound to the root-level IP. + * @param request.tokenId The token id of the NFT bound to the root-level IP. + * @param request.ipName [Optional] The name assigned to the new IP. + * @param request.contentHash [Optional] The content hash of the IP being registered. + * @param request.uri [Optional] An external URI to link to the IP. + * @param request.txOptions [Optional] The transaction options. + * @returns A Promise that resolves to an object containing the transaction hash and optional IP ID if waitForTxn is set to true. + * @throws + * @emits RootIPRegistered (msg.sender, ipId, policyId) */ public async registerRootIp(request: RegisterRootIpRequest): Promise { try { @@ -58,10 +68,20 @@ export class IPAssetClient { } /** - * Register a derivative IP on Story Protocol based on the specified input asset data. - * - * @param request - the request object that contains all data needed to register a derivative IP. - * @returns the response object that contains results from the IP creation. + * Registers derivative IPs into the protocol. Derivative IPs are IP assets that inherit policies from + * parent IPs by burning acquired license NFTs. + * @param request The request object that contains all data needed to register a root IP. + * @param request.licenseIds The policy that identifies the licensing terms of the IP. + * @param request.tokenContract The address of the NFT bound to the derivative IP. + * @param request.tokenId The token id of the NFT bound to the derivative IP. + * @param request.ipName [Optional] The name assigned to the new IP. + * @param request.contentHash [Optional] The content hash of the IP being registered. + * @param request.uri [Optional] An external URI to link to the IP. + * @param request.minRoyalty [Optional] The minimum royalty percentage that the IP owner will receive. + * @param request.txOptions [Optional] The transaction options. + * @returns A Promise that resolves to an object containing the transaction hash and optional IP ID if waitForTxn is set to true. + * @throws + * @emits RootIPRegistered (msg.sender, ipId, policyId) */ public async registerDerivativeIp( request: RegisterDerivativeIpRequest, diff --git a/packages/core-sdk/src/resources/license.ts b/packages/core-sdk/src/resources/license.ts index a2b61228..2eff9e12 100644 --- a/packages/core-sdk/src/resources/license.ts +++ b/packages/core-sdk/src/resources/license.ts @@ -19,6 +19,18 @@ export class LicenseClient { this.rpcClient = rpcClient; } + /** + * Mints license NFTs representing a policy granted by a set of ipIds (licensors). This NFT needs to be + * burned in order to link a derivative IP with its parents. If this is the first combination of policy and + * licensors, a new licenseId will be created. If not, the license is fungible and an id will be reused. + * @dev Only callable by the licensing module. + * @param request The request object containing necessary data to mint a license. + * @param request.policyId The ID of the policy to be minted + * @param request.licensorIpId_ The ID of the IP granting the license (ie. licensor) + * @param request.mintAmount Number of licenses to mint. License NFT is fungible for same policy and same licensors + * @param request.receiver Receiver address of the minted license NFT(s). + * @return licenseId The ID of the minted license NFT(s). + */ public async mintLicense(request: MintLicenseRequest): Promise { try { const IPAccountConfig = { diff --git a/packages/core-sdk/src/resources/permission.ts b/packages/core-sdk/src/resources/permission.ts index 4179ff1a..4844a1db 100644 --- a/packages/core-sdk/src/resources/permission.ts +++ b/packages/core-sdk/src/resources/permission.ts @@ -15,16 +15,29 @@ export class PermissionClient { } /** - * Set Permission based on the specified input - * - * @param request - the request object that contains all data needed to set permission. - * @returns the response object that contains results from the set permission. + * Sets the permission for a specific function call + * Each policy is represented as a mapping from an IP account address to a signer address to a recipient + * address to a function selector to a permission level. The permission level can be 0 (ABSTAIN), 1 (ALLOW), or + * 2 (DENY). + * By default, all policies are set to 0 (ABSTAIN), which means that the permission is not set. + * The owner of ipAccount by default has all permission. + * address(0) => wildcard + * bytes4(0) => wildcard + * Specific permission overrides wildcard permission. + * @param request The request object containing necessary data to set permissions. + * @param ipAccount The address of the IP account that grants the permission for `signer` + * @param signer The address that can call `to` on behalf of the `ipAccount` + * @param to The address that can be called by the `signer` (currently only modules can be `to`) + * @param func The function selector string of `to` that can be called by the `signer` on behalf of the `ipAccount` + * @param permission The new permission level + * @returns A Promise that resolves to an object containing the transaction hash + * @emits PermissionSet (ipAccountOwner, ipAccount, signer, to, func, permission) */ public async setPermission(request: setPermissionsRequest): Promise { try { const IPAccountConfig = { abi: IPAccountABI, - address: getAddress(request.ipAsset), + address: getAddress(request.ipAccount), }; const { request: call } = await this.rpcClient.simulateContract({ @@ -37,7 +50,7 @@ export class PermissionClient { abi: AccessControllerConfig.abi, functionName: "setPermission", args: [ - getAddress(request.ipAsset), // 0x Address + getAddress(request.ipAccount), // 0x Address getAddress(request.signer), // 0x Address getAddress(request.to), // 0x Address request.func as Hex, // bytes4 diff --git a/packages/core-sdk/src/types/resources/permission.ts b/packages/core-sdk/src/types/resources/permission.ts index ed4219f3..529774a4 100644 --- a/packages/core-sdk/src/types/resources/permission.ts +++ b/packages/core-sdk/src/types/resources/permission.ts @@ -1,9 +1,9 @@ import { TxOptions } from "../options"; export type setPermissionsRequest = { - ipAsset: string; - signer: string; - to: string; + ipAccount: `0x${string}`; + signer: `0x${string}`; + to: `0x${string}`; func: string; permission: number; txOptions?: TxOptions;