Merge pull request #673 from nevermined-io/feat/updated_doc

SDK Documentation Update (WIP)

integration/nevermined/ConsumeExternalDDOAsset.test.ts

@@ -97,7 +97,6 @@ describe('Consume Asset (Documentation example)', () => {
       'access',
       nevermined.keeper.templates.accessTemplate.params(consumer),
       consumer,
-      publisher,
     )
 
     assert.isDefined(agreementId)

integration/nevermined/NFT721Templates.test.ts

@@ -766,7 +766,6 @@ describe('NFT721Templates E2E', () => {
           ddo,
           nft721AccessTemplate.params(collector1.getId()),
           collector1,
-          collector1,
         )
         assert.isDefined(result)
 
@@ -816,7 +815,6 @@ describe('NFT721Templates E2E', () => {
           ddo,
           nft721SalesTemplate.params(collector2.getId()),
           collector2,
-          collector2,
         )
         assert.isDefined(result)
 

integration/nevermined/NFTTemplates.test.ts

@@ -750,7 +750,6 @@ describe('NFTTemplates E2E', () => {
           ddo,
           nftAccessTemplate.params(collector1.getId(), numberNFTs),
           collector1,
-          collector1,
         )
         assert.isDefined(result)
 
@@ -803,7 +802,6 @@ describe('NFTTemplates E2E', () => {
           ddo,
           nftSalesTemplate.params(collector2.getId(), numberNFTs2),
           collector2,
-          collector2,
         )
         assert.isDefined(result)
 
@@ -972,7 +970,6 @@ describe('NFTTemplates E2E', () => {
           ddo,
           nftSalesTemplate.params(collector1.getId(), numberNFTs),
           collector1,
-          collector1,
         )
         assert.isDefined(result)
 
@@ -1049,7 +1046,6 @@ describe('NFTTemplates E2E', () => {
           'nft-sales',
           numberNFTs,
           artist,
-          gallery,
         )
         assert.isTrue(receipt)
 

integration/nevermined/RegisterAccessTemplate.test.ts

@@ -267,7 +267,6 @@ describe('Register Escrow Access Template', () => {
         ddo,
         accessTemplate.params(consumer),
         consumer,
-        consumer,
       )
 
       assert.match(agreementId, /^0x[a-f0-9]{64}$/i)

integration/nevermined/RegisterEscrowComputeExecutionTemplate.test.ts

@@ -291,7 +291,6 @@ describe('Register Escrow Compute Execution Template', () => {
         ddo,
         escrowComputeExecutionTemplate.params(consumer),
         consumer,
-        publisher,
       )
 
       assert.match(agreementId, /^0x[a-f0-9]{64}$/i)

integration/nevermined/SecondaryMarket.test.ts

@@ -212,7 +212,6 @@ describe('Secondary Markets', () => {
           ddo,
           nftSalesTemplate.params(collector1.getId(), numberNFTs),
           collector1,
-          collector1,
         )
         assert.isDefined(result)
 
@@ -299,7 +298,6 @@ describe('Secondary Markets', () => {
           ddo,
           nftAccessTemplate.params(collector1.getId(), numberNFTs),
           collector1,
-          collector1,
         )
         assert.isDefined(result)
 
@@ -392,7 +390,6 @@ describe('Secondary Markets', () => {
           ddo,
           nftSalesTemplate.params(collector2.getId(), numberNFTs2),
           collector2,
-          collector2,
         )
         assert.isDefined(result)
 
@@ -518,7 +515,6 @@ describe('Secondary Markets', () => {
           ddo,
           nftAccessTemplate.params(collector2.getId(), numberNFTs),
           collector2,
-          collector2,
         )
         assert.isDefined(result)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevermined-io/sdk",
-  "version": "3.0.12",
+  "version": "3.0.13",
   "description": "Javascript SDK for connecting with Nevermined Data Platform ",
   "main": "./dist/node/sdk.js",
   "typings": "./dist/node/sdk.d.ts",

src/constants/AssetConstants.ts

@@ -1,8 +1,13 @@
 export const NETWORK_FEE_DENOMINATOR = 10000n
 
+// The type of the encryption methods supported for the private data included in the metadata
 export type EncryptionMethod = 'PSK-RSA' | 'PSK-ECDSA'
 
+// The default encryption method
 export const DEFAULT_ENCRYPTION_METHOD = 'PSK-RSA' as EncryptionMethod
 
+// The Ethereum zero address
 export const ZeroAddress = '0x0000000000000000000000000000000000000000'
+
+// The address to indicate that a payment is done in the native token of the network and not a ERC20 token
 export const NativeTokenAddress = '0x0000000000000000000000000000000000000000'

src/ddo/DDO.ts

@@ -38,12 +38,20 @@ export const DEPENDENCIES_RELEASE_CONDITION = ['access', 'serviceExecution', 'tr
 /**
  * Fill some static parameters that depends on the metadata.
  *
- * @param conditions - Conditions to fill.
- * @param ddo - DDO related to this conditions.
+ * @param serviceType - The type of the service "access", "nft-sales", etc.
+ * @param conditions - List of conditions to fill.
+ * @param owner - Owner of the asset.
  * @param assetPrice -Rewards distribution
+ * @param did - The DID of the asset.
+ * @param erc20TokenContract - The address of the ERC20 token contract used for payment (0x0 address if native token).
+ * @param nftTokenContract - The address of the NFT token contract used.
+ * @param nftHolder - The address of the NFT holder.
  * @param nftAmount - Number of nfts to handle
- * @param erc20TokenContract - Number of nfts to handle
- * @param nftTokenContract - Number of nfts to handle
+ * @param nftTransfer - If the nft will be transferred (true) or minted (false)
+ * @param duration - Duration if it's a subscription
+ * @param fulfillAccessTimeout - Timeout for the fulfill of the access service
+ * @param fulfillAccessTimelock - Timelock for the fulfill of the access service
+ * @param tokenId - The token id of the NFT
  *
  * @returns Filled conditions.
  */
@@ -148,8 +156,8 @@ function getParameter(
 }
 
 /**
- * DID Descriptor Object.
- * Contains all the data related to an asset.
+ * DID Descriptor Object (DDO).
+ * Contains all the metadata related to an asset, including the description and the services available.
  */
 export class DDO {
   /**
@@ -172,6 +180,13 @@ export class DDO {
     return new DDO(ddo)
   }
 
+  /**
+   * It creates an authorization service that can be included later as part of a DDO
+   * @param neverminedNodeUri URL of the Nevermined Node managing this asset
+   * @param publicKey Public key of the user
+   * @param method Encryption method
+   * @returns The authorization service
+   */
   public static createAuthorizationService(
     neverminedNodeUri: string,
     publicKey: string,
@@ -220,6 +235,13 @@ export class DDO {
     })
   }
 
+  /**
+   * It gets an instance of a DDO with the basic structure
+   * @param userId The unique identifier of the user
+   * @param publisherAddress The address of the publisher
+   * @param appId The application id
+   * @returns a {@link DDO} instance
+   */
   public static getInstance(userId: string, publisherAddress: string, appId?: string): DDO {
     return new DDO({
       id: '',
@@ -244,18 +266,27 @@ export class DDO {
     })
   }
 
+  /**
+   * It gets a new date formatted
+   * @param date the date to format
+   * @returns the date string formatted
+   */
   public static getNewDateFormatted(date: Date = new Date()) {
     return date.toISOString().replace(/\.[0-9]{3}/, '')
   }
 
+  /**
+   * It returns the DDO id without the prefix
+   * @returns the DID without the prefix
+   */
   public shortId(): string {
     return this.id.replace('did:nv:', '')
   }
 
   /**
-   * Finds a service of a DDO by index.
+   * Finds a service of a DDO by index number.
    * @param index - index of the service in the DDO.
-   * @returns Service.
+   * @returns {@link Service}.
    */
   public findServiceByIndex<T extends ServiceType>(index: number): Service<T> {
     if (isNaN(index)) {

src/ddo/NvmAppMetadata.ts

@@ -8,6 +8,14 @@ import {
 } from '../types/DDOTypes'
 
 export class NvmAppMetadata {
+  /**
+   * It returns a metadata template for a subscription with time limit
+   * @param name the name of the subscription
+   * @param author the author of the subscrpiton
+   * @param timeMeasure the string defining the time measure
+   * @param customData any key-value pair to be included in the metadata
+   * @returns {@link Metadata}
+   */
   public static getTimeSubscriptionMetadataTemplate(
     name: string,
     author: string,
@@ -28,6 +36,13 @@ export class NvmAppMetadata {
     return metadata
   }
 
+  /**
+   * It returns a metadata template for a credits limitted subscription
+   * @param name the name of the subscription
+   * @param author the author of the subscrpiton
+   * @param customData any key-value pair to be included in the metadata
+   * @returns {@link Metadata}
+   */
   public static getCreditsSubscriptionMetadataTemplate(
     name: string,
     author: string,
@@ -46,6 +61,13 @@ export class NvmAppMetadata {
     return metadata
   }
 
+  /**
+   * It returns a metadata template for subscription
+   * @param name the name of the subscription
+   * @param author the author of the subscrpiton
+   * @param customData any key-value pair to be included in the metadata
+   * @returns {@link Metadata}
+   */
   public static getSubscriptionMetadataTemplate(
     name: string,
     author: string,
@@ -73,6 +95,23 @@ export class NvmAppMetadata {
     return _metadata
   }
 
+  /**
+   * It returns a metadata template for Web Service
+   * @param name the name of the subscription
+   * @param author the author of the subscrpiton
+   * @param endpoints the list of endpoints
+   * @param openEndpoints the list of open endpoints (not protected)
+   * @param openApiEndpoint the openApi endpoint endpoint if any
+   * @param serviceType the type of the service
+   * @param authType the type of authentication required by the service
+   * @param authToken the token to be used for authentication (if authType is oauth or bearer)
+   * @param authUser the username to be used for authentication (if authType is basic)
+   * @param authPassword the password to be used for authentication (if authType is basic)
+   * @param isPriceDynamic if the price is dynamic
+   * @param customData any key-value pair to be included in the metadata
+   * @param nonce the nonce to be included in the metadata
+   * @returns {@link Metadata}
+   */
   public static getServiceMetadataTemplate(
     name: string,
     author: string,
@@ -143,6 +182,13 @@ export class NvmAppMetadata {
     return serviceMetadata
   }
 
+  /**
+   * It gets a metadata template for a file type of asset (datasets, moldels, algorithms, etc.)
+   * @param name the name of the asset
+   * @param author the autor of the asset
+   * @param customData key-value pairs to be included in the metadata
+   * @returns {@link Metadata}
+   */
   public static getFileMetadataTemplate(
     name: string,
     author: string,

src/events/ContractEvent.ts

@@ -6,7 +6,18 @@ import { searchAbiEvent } from '../nevermined/utils/BlockchainViemUtils'
 import { Nevermined } from '../nevermined/Nevermined'
 import { Web3Clients } from '../Instantiable.abstract'
 
+/**
+ * Class to handle Smart Contract events directly connected to a blockchain node
+ */
 export class ContractEvent extends NeverminedEvent {
+  /**
+   * It gets a new instance of ContractEvent
+   * @param contract contract instance
+   * @param eventEmitter events emitter implementation
+   * @param nevermined the Nevermined instance
+   * @param client the blockchain client
+   * @returns the ContractEvent instance
+   */
   public static getInstance(
     contract: ContractBase,
     eventEmitter: EventEmitter,
@@ -22,6 +33,11 @@ export class ContractEvent extends NeverminedEvent {
     return instance
   }
 
+  /**
+   * It returns the events matching a given filter
+   * @param options event filter options
+   * @returns {@link EventResult}
+   */
   public async getEventData(options: EventOptions): EventResult {
     if (!this.eventExists(options.eventName) || !options.filterJsonRpc) {
       throw new KeeperError(
@@ -47,6 +63,12 @@ export class ContractEvent extends NeverminedEvent {
     }
   }
 
+  /**
+   * It returns the events matching a given filter depending on the blockchain network connected
+   * This necessary for some networks and/or web3 providers which limit the number of blocks to query
+   * @param options event filter options
+   * @returns {@link EventResult}
+   */
   public async getPastEvents(options: EventOptions): EventResult {
     try {
       const chainId = this.client.chain?.id
@@ -73,10 +95,19 @@ export class ContractEvent extends NeverminedEvent {
     }
   }
 
+  /**
+   * It returns the current block chain block number
+   * @returns the block number
+   */
   public async getBlockNumber(): Promise<bigint> {
     return await this.client.public.getBlockNumber()
   }
 
+  /**
+   * It checks if an event exists on the contract definition
+   * @param eventName the event name
+   * @returns true if the event exists, false otherwise
+   */
   private eventExists(eventName: string): boolean {
     try {
       const signature = searchAbiEvent(this.contract.contract.abi, eventName)
@@ -86,6 +117,12 @@ export class ContractEvent extends NeverminedEvent {
     }
   }
 
+  /**
+   * It returns the indexed parameters of an event
+   * @param eventName the name of the event
+   * @param filter tge event filter
+   * @returns the array of indexed parameters
+   */
   private filterToArgs(eventName: string, filter: FilterContractEvent): Array<any> {
     const signature = searchAbiEvent(this.contract.contract.abi, eventName)
     // @ts-ignore