add more comments (#68)

add more comments

packages/core-sdk/src/resources/dispute.ts

@@ -23,7 +23,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.
@@ -70,7 +70,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.
@@ -102,7 +102,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.

packages/core-sdk/src/resources/ipAsset.ts

@@ -23,10 +23,19 @@ 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.
+   * @emits RootIPRegistered (msg.sender, ipId, policyId)
    */
   public async registerRootIp(request: RegisterRootIpRequest): Promise<RegisterRootIpResponse> {
     try {
@@ -60,10 +69,19 @@ 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.
+   * @emits RootIPRegistered (msg.sender, ipId, policyId)
    */
   public async registerDerivativeIp(
     request: RegisterDerivativeIpRequest,

packages/core-sdk/src/resources/license.ts

@@ -22,6 +22,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<MintLicenseResponse> {
     try {
       const IPAccountConfig = {

packages/core-sdk/src/resources/permission.ts

@@ -17,10 +17,23 @@ 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 request.ipAsset The address of the IP account that grants the permission for `signer`
+   *   @param request.signer The address that can call `to` on behalf of the `ipAccount`
+   *   @param request.to The address that can be called by the `signer` (currently only modules can be `to`)
+   *   @param request.func The function selector string of `to` that can be called by the `signer` on behalf of the `ipAccount`
+   *   @param request.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<setPermissionsResponse> {
     try {

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;
+  ipAsset: `0x${string}`;
+  signer: `0x${string}`;
+  to: `0x${string}`;
   func: string;
   permission: number;
   txOptions?: TxOptions;

packages/core-sdk/test/integration/permission.test.ts

@@ -27,7 +27,7 @@ describe("Permission Functions", () => {
       const response = await expect(
         client.permission.setPermission({
           ipAsset: "0x004e38104adc39cbf4cea9bd8876440a969e3d0b",
-          signer: process.env.TEST_WALLET_ADDRESS!,
+          signer: process.env.TEST_WALLET_ADDRESS as `0x${string}`,
           to: "0x2ac240293f12032E103458451dE8A8096c5A72E8",
           func: "0x00000000",
           permission: 1,