Merge pull request #1183 from PolymeshAssociation/beta

Release v24

Author: VictorVicente

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 Polymath Inc.
+   Copyright 2024 Verein Polymesh
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -24,13 +24,9 @@ This release is compatible with Polymesh v6.x.x
 
 The Polymesh SDK's main goal is to provide external developers with a set of tools that will allow them to build powerful applications that interact with the Polymesh protocol. It focuses on abstracting away all the complexities of the Polymesh blockchain and expose a simple but complete interface. The result is a feature-rich, user-friendly node.js library.
 
-### Before moving on
-
-This document assumes you are already familiar with [Security Tokens](https://thesecuritytokenstandard.org/) in general and [Polymath](https://www.polymath.network/) as well as [Polymesh](https://polymath.network/polymesh) in particular.
-
 ### Technical Pre-requisites
 
-In order to use the Polymath SDK, you must install [node](https://nodejs.org/) \(version 16\) and [npm](https://www.npmjs.com/). The library is written in [typescript](https://www.typescriptlang.org/), but can also be used in plain javascript. This document will assume you are using typescript, but the translation to javascript is very simple.
+In order to use the Polymesh SDK, you must install [node](https://nodejs.org/) \(version 16\) and [npm](https://www.npmjs.com/). The library is written in [typescript](https://www.typescriptlang.org/), but can also be used in plain javascript. This document will assume you are using typescript, but the translation to javascript is very simple.
 
 ### Documentation
 
@@ -71,8 +67,8 @@ async function run() {
         mnemonic: '//Alice', //A "well known" mnemonic, often with sudo privileges on development chains
       },
       {
-        mnemonic: 'forest end mail art wish leave truth else ignore royal knife river' // most mnemonics are 12 words
-      }
+        mnemonic: 'forest end mail art wish leave truth else ignore royal knife river', // most mnemonics are 12 words
+      },
     ],
   });
   const polyClient = await Polymesh.connect({
@@ -133,11 +129,11 @@ Creating transactions is a two-step process. First a procedure is created, which
 The SDK exposes getter functions that will return entities, which may have their own functions:
 
 ```typescript
-  const assetsPage = await polyClient.assets.get({ size: new BigNumber(20) })
-  const asset = assetsPage.data[0]
+const assetsPage = await polyClient.assets.get({ size: new BigNumber(20) });
+const asset = assetsPage.data[0];
 
-  const assetDetails = await asset.details()
-  console.log('asset details:', assetDetails)
+const assetDetails = await asset.details();
+console.log('asset details:', assetDetails);
 ```
 
 Note: Some getters require "middleware" to be configured, which is a chain indexer that aids in historical queries. All such methods will have a comment indicating this requirement.
@@ -148,4 +144,4 @@ The SDK uses the class `Account` as an abstraction for a public/private key pair
 
 The only thing an `Account` holds is the POLYX utility token. Ownership of any asset on the Polymesh chain requires an `Identity`. This process involves a trusted provider writing a claim to the chain, stating that this person has completed a "customer due diligence" (CDD) process. For development chains, the mnemonic `//Alice` can create CDD claims by default.
 
-Polymesh uses an `Identity` to provide flexibility in managing permissions. Portfolios can be created, and secondary keys can be granted permission to provide fine grained authorization.
+Polymesh uses an `Identity` to provide flexibility in managing permissions. Portfolios can be created, and secondary keys can be granted permission to provide fine grained authorization.

SECURITY.md

@@ -6,9 +6,9 @@ Do not open issues that might have security implications! It is critical that se
 
 Vulnerabilities can be reported by emailing repository admins:
 
-- Víctor Vicente victor@polymath.network
-- Eric Richardson ericrichardson@polymath.network
-- Prashant Bajpai prashant@polymath.network
+- Víctor Vicente victor@polymesh.network
+- Eric Richardson eric@polymesh.network
+- Prashant Bajpai prashant@polymesh.network
 
 Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
 

package.json

@@ -55,8 +55,9 @@
     "@polkadot/dev-ts": "^0.76.22",
     "@polkadot/typegen": "10.9.1",
     "@polymeshassociation/local-signing-manager": "^3.0.1",
+    "@polymeshassociation/polymesh-types": "^5.9.1",
     "@polymeshassociation/signing-manager-types": "^3.0.0",
-    "@polymeshassociation/typedoc-theme": "^1.1.0",
+    "@polymeshassociation/typedoc-theme": "^1.2.0",
     "@semantic-release/changelog": "^6.0.1",
     "@types/bluebird": "^3.5.38",
     "@types/jest": "29.5.4",
@@ -102,9 +103,9 @@
     "tsconfig-paths": "^4.2.0",
     "tsconfig-paths-webpack-plugin": "^4.1.0",
     "ttypescript": "1.5.15",
-    "typedoc": "0.23.5",
+    "typedoc": "0.24.8",
     "typedoc-github-wiki-theme": "^1.0.1",
-    "typedoc-plugin-markdown": "3.13.2",
+    "typedoc-plugin-markdown": "3.17.1",
     "typescript": "4.6.2",
     "webpack": "^5.88.2",
     "webpack-cli": "^5.1.4",

scripts/fetchDefinitions.js

@@ -1,11 +1,12 @@
 /* eslint-disable */
-const http = require('http');
 const path = require('path');
 const fs = require('fs');
 const rimraf = require('rimraf');
 const util = require('util');
 const { forEach, camelCase, mapKeys } = require('lodash');
-const { NODE_URL, SCHEMA_PORT } = require('./consts');
+
+const { typesBundle } = require('@polymeshassociation/polymesh-types');
+const types = require('@polymeshassociation/polymesh-types/types/6.1.x.json');
 
 const definitionsDir = path.resolve('src', 'polkadot');
 const typesDir = path.resolve(definitionsDir, 'polymesh');
@@ -111,17 +112,15 @@ function writeDefinitions(schemaObj) {
   fs.writeFileSync(path.resolve(definitionsDir, 'definitions.ts'), defExports);
 }
 
-http.get(`http://${NODE_URL}:${SCHEMA_PORT}/polymesh_schema.json`, res => {
-  const chunks = [];
-  res.on('data', chunk => {
-    chunks.push(chunk);
-  });
-
-  res.on('end', () => {
-    const schema = Buffer.concat(chunks);
-    const schemaObj = JSON.parse(schema);
-    transformSchema(schemaObj);
-
-    writeDefinitions(schemaObj);
-  });
-});
+(() => {
+  const { rpc, runtime, signedExtensions } = typesBundle.spec.polymesh_dev;
+  const schema = {
+    types,
+    rpc,
+    runtime,
+    signedExtensions,
+  };
+
+  transformSchema(schema);
+  writeDefinitions(schema);
+})();

scripts/transactions.json

@@ -256,7 +256,9 @@
     "exempt_ticker_affirmation": "exempt_ticker_affirmation",
     "remove_ticker_affirmation_exemption": "remove_ticker_affirmation_exemption",
     "pre_approve_ticker": "pre_approve_ticker",
-    "remove_ticker_pre_approval": "remove_ticker_pre_approval"
+    "remove_ticker_pre_approval": "remove_ticker_pre_approval",
+    "add_mandatory_mediators": "add_mandatory_mediators",
+    "remove_mandatory_mediators": "remove_mandatory_mediators"
   },
   "CapitalDistribution": {
     "distribute": "distribute",
@@ -387,7 +389,12 @@
     "affirm_with_receipts_with_count": "affirm_with_receipts_with_count",
     "affirm_instruction_with_count": "affirm_instruction_with_count",
     "reject_instruction_with_count": "reject_instruction_with_count",
-    "withdraw_affirmation_with_count": "withdraw_affirmation_with_count"
+    "withdraw_affirmation_with_count": "withdraw_affirmation_with_count",
+    "add_instruction_with_mediators": "add_instruction_with_mediators",
+    "add_and_affirm_with_mediators": "add_and_affirm_with_mediators",
+    "affirm_instruction_as_mediator": "affirm_instruction_as_mediator",
+    "withdraw_affirmation_as_mediator": "withdraw_affirmation_as_mediator",
+    "reject_instruction_as_mediator": "reject_instruction_as_mediator"
   },
   "Statistics": {
     "add_transfer_manager": "add_transfer_manager",

sdk-docs-typedoc.json

@@ -12,6 +12,7 @@
   ],
   "entryPointStrategy": "expand",
   "out": "sdk-docs",
+  "plugin": ["@polymeshassociation/typedoc-theme", "typedoc-plugin-markdown"],
   "theme": "polymesh-docs",
   "exclude": [
     "src/internal.ts",

src/api/client/Assets.ts

@@ -274,9 +274,7 @@ export class Assets {
    *
    * @note supports pagination
    */
-  public async get(
-    paginationOpts?: PaginationOptions
-  ): Promise<ResultSet<FungibleAsset | NftCollection>> {
+  public async get(paginationOpts?: PaginationOptions): Promise<ResultSet<Asset>> {
     const {
       context: {
         polymeshApi: {

src/api/client/Claims.ts

@@ -213,7 +213,7 @@ export class Claims {
       trustedClaimIssuers: trustedClaimIssuers?.map(trustedClaimIssuer =>
         signerToString(trustedClaimIssuer)
       ),
-      claimTypes: claimTypes?.map(ct => ClaimTypeEnum[ct]),
+      claimTypes: Array.isArray(claimTypes) ? claimTypes.map(ct => ClaimTypeEnum[ct]) : undefined,
       includeExpired,
     };
 

src/api/client/Identities.ts

@@ -1,5 +1,7 @@
 import { createPortfolioTransformer } from '~/api/entities/Venue';
 import {
+  allowIdentityToCreatePortfolios,
+  AllowIdentityToCreatePortfoliosParams,
   attestPrimaryKeyRotation,
   AuthorizationRequest,
   ChildIdentity,
@@ -9,6 +11,8 @@ import {
   Identity,
   NumberedPortfolio,
   registerIdentity,
+  revokeIdentityToCreatePortfolios,
+  RevokeIdentityToCreatePortfoliosParams,
   rotatePrimaryKey,
 } from '~/internal';
 import {
@@ -18,7 +22,8 @@ import {
   RegisterIdentityParams,
   RotatePrimaryKeyParams,
 } from '~/types';
-import { asIdentity, createProcedureMethod } from '~/utils/internal';
+import { identityIdToString } from '~/utils/conversion';
+import { asIdentity, assertIdentityExists, createProcedureMethod } from '~/utils/internal';
 
 /**
  * Handles all Identity related functionality
@@ -47,17 +52,12 @@ export class Identities {
       context
     );
 
-    this.createPortfolio = createProcedureMethod<
-      { name: string },
-      { names: string[] },
-      NumberedPortfolio[],
-      NumberedPortfolio
-    >(
+    this.createPortfolio = createProcedureMethod(
       {
         getProcedureAndArgs: args => [
           createPortfolios,
           {
-            names: [args.name],
+            portfolios: [{ name: args.name, ownerDid: args.ownerDid }],
           },
         ],
         transformer: createPortfolioTransformer,
@@ -67,7 +67,10 @@ export class Identities {
 
     this.createPortfolios = createProcedureMethod(
       {
-        getProcedureAndArgs: args => [createPortfolios, args],
+        getProcedureAndArgs: args => [
+          createPortfolios,
+          { portfolios: args.names.map(name => ({ name, ownerDid: args.ownerDid })) },
+        ],
       },
       context
     );
@@ -78,6 +81,16 @@ export class Identities {
       },
       context
     );
+
+    this.allowIdentityToCreatePortfolios = createProcedureMethod(
+      { getProcedureAndArgs: args => [allowIdentityToCreatePortfolios, args] },
+      context
+    );
+
+    this.revokeIdentityToCreatePortfolios = createProcedureMethod(
+      { getProcedureAndArgs: args => [revokeIdentityToCreatePortfolios, args] },
+      context
+    );
   }
 
   /**
@@ -120,13 +133,22 @@ export class Identities {
 
   /**
    * Create a new Portfolio under the ownership of the signing Identity
+   * @note the `ownerDid` is optional. If provided portfolios will be created as Custody Portfolios under the `ownerDid`
    */
-  public createPortfolio: ProcedureMethod<{ name: string }, NumberedPortfolio[], NumberedPortfolio>;
+  public createPortfolio: ProcedureMethod<
+    { name: string; ownerDid?: string },
+    NumberedPortfolio[],
+    NumberedPortfolio
+  >;
 
   /**
    * Creates a set of new Portfolios under the ownership of the signing Identity
+   * @note the `ownerDid` is optional. If provided portfolios will be created as Custody Portfolios under the `ownerDid`
    */
-  public createPortfolios: ProcedureMethod<{ names: string[] }, NumberedPortfolio[]>;
+  public createPortfolios: ProcedureMethod<
+    { names: string[]; ownerDid?: string },
+    NumberedPortfolio[]
+  >;
 
   /**
    * Create an Identity instance from a DID
@@ -165,4 +187,55 @@ export class Identities {
    *  - the signing Identity is already a child of some other identity
    */
   public createChild: ProcedureMethod<CreateChildIdentityParams, ChildIdentity>;
+
+  /**
+   * Gives permission to the Identity to create Portfolios on behalf of the signing Identity
+   *
+   * @throws if
+   *  - the provided Identity already has permissions to create portfolios for signing Identity
+   *  - the provided Identity does not exist
+   */
+  public allowIdentityToCreatePortfolios: ProcedureMethod<
+    AllowIdentityToCreatePortfoliosParams,
+    void
+  >;
+
+  /**
+   * Revokes permission from the Identity to create Portfolios on behalf of the signing Identity
+   *
+   * @throws if
+   *  - the provided Identity already does not have permissions to create portfolios for signing Identity
+   *  - the provided Identity does not exist
+   */
+  public revokeIdentityToCreatePortfolios: ProcedureMethod<
+    RevokeIdentityToCreatePortfoliosParams,
+    void
+  >;
+
+  /**
+   * Returns a list of allowed custodian did(s) for Identity
+   * @throws if
+   * - the provided Identity does not exist
+   */
+  public async getAllowedCustodians(did: string | Identity): Promise<string[]> {
+    const {
+      context: {
+        polymeshApi: { query },
+      },
+    } = this;
+
+    const identity = asIdentity(did, this.context);
+
+    await assertIdentityExists(identity);
+
+    const custodians = await query.portfolio.allowedCustodians.entries(did.toString());
+
+    return custodians.map(([storageKey]) => {
+      const {
+        args: [, custodianIdentityId],
+      } = storageKey;
+
+      return identityIdToString(custodianIdentityId);
+    });
+  }
 }