feat: 🎸 Bump SDK to v31 and drop v7 support

.dockerignore

@@ -1,3 +1,4 @@
 .git
 .env*
-node_modules/
+node_modules/
+/dist

README.md

@@ -8,7 +8,7 @@
 
 A REST API wrapper for the Polymesh blockchain.
 
-This version is compatible with chain versions 7.3.x - 8.x
+This version is compatible with chain versions 8.0.x - 8.1.x. Chain v7 is no longer supported — the SDK throws on initialization if pointed at a v7 node.
 
 ## Setup
 

package.json

@@ -52,8 +52,8 @@
     "@polymeshassociation/fireblocks-signing-manager": "^3.0.0",
     "@polymeshassociation/hashicorp-vault-signing-manager": "^4.1.0",
     "@polymeshassociation/local-signing-manager": "^4.1.1",
-    "@polymeshassociation/polymesh-sdk": "v30.0.0",
-    "@polymeshassociation/polymesh-types": "^7.4.0",
+    "@polymeshassociation/polymesh-sdk": "31.0.0",
+    "@polymeshassociation/polymesh-types": "^7.5.0",
     "@polymeshassociation/signing-manager-types": "^3.7.1",
     "class-transformer": "0.5.1",
     "class-validator": "^0.14.0",

src/accounts/accounts.controller.spec.ts

@@ -94,6 +94,8 @@ describe('AccountsController', () => {
         free: new BigNumber(10),
         locked: new BigNumber(1),
         total: new BigNumber(11),
+        reserved: new BigNumber(1),
+        frozen: new BigNumber(0),
       };
       mockAccountsService.getAccountBalance.mockResolvedValue(mockResult);
 

src/accounts/accounts.controller.ts

@@ -28,6 +28,7 @@ import { ModifyPermissionsDto } from '~/accounts/dto/modify-permissions.dto';
 import { RevokePermissionsDto } from '~/accounts/dto/revoke-permissions.dto';
 import { TransactionHistoryFiltersDto } from '~/accounts/dto/transaction-history-filters.dto';
 import { TransferPolyxDto } from '~/accounts/dto/transfer-polyx.dto';
+import { AccountBalanceModel } from '~/accounts/models/account-balance.model';
 import {
   AccountCollectionModel,
   createAccountCollectionModel,
@@ -36,7 +37,6 @@ import { AccountDetailsModel } from '~/accounts/models/account-details.model';
 import { MultiSigDetailsModel } from '~/accounts/models/multi-sig-details.model';
 import { PermissionsModel } from '~/accounts/models/permissions.model';
 import { AssetBalanceModel } from '~/assets/models/asset-balance.model';
-import { BalanceModel } from '~/assets/models/balance.model';
 import { ApiArrayResponse, ApiTransactionResponse } from '~/common/decorators/';
 import { TransactionBaseDto } from '~/common/dto/transaction-base-dto';
 import { ExtrinsicModel } from '~/common/models/extrinsic.model';
@@ -106,7 +106,8 @@ export class AccountsController {
 
   @ApiOperation({
     summary: 'Get POLYX balance of an Account',
-    description: 'This endpoint provides the free, locked and total POLYX balance of an Account',
+    description:
+      'This endpoint provides the free, locked and total POLYX balance of an Account. Note: as of chain v8, `locked` also includes funds on hold (e.g. bonded for staking), which is reflected in the `reserved` and `frozen` fields',
   })
   @ApiParam({
     name: 'account',
@@ -116,12 +117,12 @@ export class AccountsController {
   })
   @ApiOkResponse({
     description: 'Free, locked and total POLYX balance of the Account',
-    type: BalanceModel,
+    type: AccountBalanceModel,
   })
   @Get(':account/balance')
-  async getAccountBalance(@Param() { account }: AccountParamsDto): Promise<BalanceModel> {
+  async getAccountBalance(@Param() { account }: AccountParamsDto): Promise<AccountBalanceModel> {
     const accountBalance = await this.accountsService.getAccountBalance(account);
-    return new BalanceModel(accountBalance);
+    return new AccountBalanceModel(accountBalance);
   }
 
   @ApiOperation({
@@ -136,7 +137,6 @@ export class AccountsController {
     description:
       '<ul>' +
       "<li>The destination Account doesn't have an associated Identity</li>" +
-      '<li>The receiver Identity has an invalid CDD claim</li>' +
       '<li>Insufficient free balance</li>' +
       '</ul>',
   })
@@ -232,8 +232,7 @@ export class AccountsController {
 
   @ApiOperation({
     summary: 'Get pending subsidies for an Account',
-    description:
-      'Returns pending subsidy requests awaiting acceptance by the beneficiary account on chain v8',
+    description: 'Returns pending subsidy requests awaiting acceptance by the beneficiary account',
   })
   @ApiParam({
     name: 'account',
@@ -258,7 +257,7 @@ export class AccountsController {
 
   @ApiOperation({
     summary: 'Get fungible asset balances held by an Account',
-    description: 'Returns balances of all fungible assets held in the Account on chain v8',
+    description: 'Returns balances of all fungible assets held in the Account',
   })
   @ApiParam({
     name: 'account',
@@ -291,7 +290,7 @@ export class AccountsController {
 
   @ApiOperation({
     summary: 'Get NFT collections held by an Account',
-    description: 'Returns NFT collections and holdings for the Account on chain v8',
+    description: 'Returns NFT collections and holdings for the Account',
   })
   @ApiParam({
     name: 'account',

src/accounts/models/account-balance.model.ts

@@ -0,0 +1,32 @@
+/* istanbul ignore file */
+
+import { ApiProperty } from '@nestjs/swagger';
+import { BigNumber } from '@polymeshassociation/polymesh-sdk';
+
+import { BalanceModel } from '~/assets/models/balance.model';
+import { FromBigNumber } from '~/common/decorators/transformation';
+
+export class AccountBalanceModel extends BalanceModel {
+  @ApiProperty({
+    type: 'string',
+    description:
+      'POLYX placed on hold by the protocol, e.g. bonded for staking. Not part of `free` and cannot be spent until released',
+    example: '100',
+  })
+  @FromBigNumber()
+  readonly reserved: BigNumber;
+
+  @ApiProperty({
+    type: 'string',
+    description:
+      'Minimum balance (out of `total`) that must remain in the Account due to freezes/locks (e.g. vesting). May overlap with `reserved`',
+    example: '0',
+  })
+  @FromBigNumber()
+  readonly frozen: BigNumber;
+
+  constructor(model: AccountBalanceModel) {
+    super(model);
+    Object.assign(this, model);
+  }
+}

src/assets/assets.controller.spec.ts

@@ -20,6 +20,7 @@ import { AssetsService } from '~/assets/assets.service';
 import { AssetDocumentDto } from '~/assets/dto/asset-document.dto';
 import { SetStatsDto } from '~/assets/dto/transfer-restrictions/set-stats.dto';
 import { SetTransferRestrictionsDto } from '~/assets/dto/transfer-restrictions/set-transfer-restrictions.dto';
+import { IssuedInFundingRoundModel } from '~/assets/models/issued-in-funding-round.model';
 import { StatAccreditedClaimModel } from '~/assets/models/stat-claim-accredited.model';
 import { StatAffiliateClaimModel } from '~/assets/models/stat-claim-affiliate.model';
 import { StatJurisdictionClaimModel } from '~/assets/models/stat-claim-jurisdiction.model';
@@ -36,7 +37,7 @@ import { ProcessMode } from '~/common/types';
 import { MetadataService } from '~/metadata/metadata.service';
 import { PortfolioDto } from '~/portfolios/dto/portfolio.dto';
 import { processedTxResult, testValues } from '~/test-utils/consts';
-import { MockAsset, MockAuthorizationRequest } from '~/test-utils/mocks';
+import { MockAsset, MockAuthorizationRequest, MockInstruction } from '~/test-utils/mocks';
 import { MockAssetService, mockMetadataServiceProvider } from '~/test-utils/service-mocks';
 
 const { signer, did, txResult, assetId } = testValues;
@@ -437,6 +438,33 @@ describe('AssetsController', () => {
       expect(result).toEqual(processedTxResult);
       expect(mockAssetsService.transferFunds).toHaveBeenCalledWith(body);
     });
+
+    it('should return the pending Instruction when the transfer does not settle immediately', async () => {
+      const from = new AssetHolderDto({
+        type: AssetHolderType.account,
+        address: 'fromAddress',
+      });
+      const to = new AssetHolderDto({
+        type: AssetHolderType.account,
+        address: 'toAddress',
+      });
+      const amount = new BigNumber(100);
+      const body = { signer, from, to, asset: assetId, amount };
+
+      const mockInstruction = new MockInstruction();
+
+      mockAssetsService.transferFunds.mockResolvedValue({
+        ...txResult,
+        result: mockInstruction,
+      });
+
+      const result = await controller.transferFunds(body);
+
+      expect(result).toEqual({
+        ...processedTxResult,
+        instruction: mockInstruction,
+      });
+    });
   });
 
   describe('approveAllowance', () => {
@@ -519,6 +547,21 @@ describe('AssetsController', () => {
     });
   });
 
+  describe('getIssuedInFundingRound', () => {
+    it('should call the service and return the amount issued in the funding round', async () => {
+      mockAssetsService.getIssuedInFundingRound.mockResolvedValue(new BigNumber(1000));
+
+      const result = await controller.getIssuedInFundingRound({
+        asset: assetId,
+        round: 'Series A',
+      });
+
+      expect(result).toEqual(
+        new IssuedInFundingRoundModel({ fundingRound: 'Series A', issued: new BigNumber(1000) })
+      );
+    });
+  });
+
   describe('addRequiredMediators', () => {
     it('should call the service and return the results', async () => {
       const mediators = ['someDid'];

src/assets/assets.controller.ts

@@ -10,14 +10,15 @@ import {
   ApiTags,
   ApiUnprocessableEntityResponse,
 } from '@nestjs/swagger';
-import { Asset } from '@polymeshassociation/polymesh-sdk/types';
+import { Asset, Instruction } from '@polymeshassociation/polymesh-sdk/types';
 
 import { AssetsService } from '~/assets/assets.service';
 import { createAssetDetailsModel } from '~/assets/assets.util';
 import { ApproveAllowanceDto } from '~/assets/dto/approve-allowance.dto';
 import { AssetParamsDto } from '~/assets/dto/asset-params.dto';
 import { ControllerTransferDto } from '~/assets/dto/controller-transfer.dto';
 import { CreateAssetDto } from '~/assets/dto/create-asset.dto';
+import { FundingRoundParamsDto } from '~/assets/dto/funding-round-params.dto';
 import { GetAllowanceParamsDto } from '~/assets/dto/get-allowance-params.dto';
 import { IssueDto } from '~/assets/dto/issue.dto';
 import { LinkTickerDto } from '~/assets/dto/link-ticker.dto';
@@ -34,7 +35,9 @@ import { AssetDocumentModel } from '~/assets/models/asset-document.model';
 import { AssetStatModel } from '~/assets/models/asset-stat.model';
 import { CreatedAssetModel } from '~/assets/models/created-asset.model';
 import { IdentityBalanceModel } from '~/assets/models/identity-balance.model';
+import { IssuedInFundingRoundModel } from '~/assets/models/issued-in-funding-round.model';
 import { RequiredMediatorsModel } from '~/assets/models/required-mediators.model';
+import { TransferFundsResultModel } from '~/assets/models/transfer-funds-result.model';
 import { TransferRestrictionsModel } from '~/assets/models/transfer-restrictions.model';
 import { TransferRestrictionsValueModel } from '~/assets/models/transfer-restrictions-values.model';
 import { VenueFilteringDetailsModel } from '~/assets/models/venue-filtering-details.model';
@@ -84,16 +87,24 @@ export class AssetsController {
   @ApiOperation({
     summary: 'Transfer funds between asset holders',
     description:
-      'Transfers fungible tokens or NFTs between asset holders (accounts or portfolios) owned by the same identity',
+      'Transfers fungible tokens or NFTs between asset holders (accounts or portfolios). The holders may belong to different Identities, in which case a settlement Instruction is created and auto affirmed on behalf of the sender. It settles in the same transaction if the receiving Identity affirms automatically, otherwise the returned Instruction is left pending the receiver affirmation',
   })
   @ApiTransactionResponse({
-    description: 'Details about the transaction',
-    type: TransactionQueueModel,
+    description:
+      'Details about the transaction, along with the pending Instruction if the transfer did not settle immediately',
+    type: TransferFundsResultModel,
   })
   @Post('transfer-funds')
   public async transferFunds(@Body() params: TransferFundsDto): Promise<TransactionResponseModel> {
     const result = await this.assetsService.transferFunds(params);
-    return handleServiceResult(result);
+
+    const resolver: TransactionResolver<Instruction | undefined> = ({
+      result: instruction,
+      transactions,
+      details,
+    }) => new TransferFundsResultModel({ instruction, transactions, details });
+
+    return handleServiceResult(result, resolver);
   }
 
   @ApiTags('nfts')
@@ -569,8 +580,7 @@ export class AssetsController {
 
   @ApiOperation({
     summary: 'Approve fungible asset allowance',
-    description:
-      'Approves a spender account allowance for transferring fungible asset tokens on chain v8',
+    description: 'Approves a spender account allowance for transferring fungible asset tokens',
   })
   @ApiParam({
     name: 'asset',
@@ -665,6 +675,36 @@ export class AssetsController {
     return new RequiredMediatorsModel({ mediators });
   }
 
+  @ApiOperation({
+    summary: 'Get the total amount issued in a funding round',
+    description:
+      'This endpoint returns the total amount of the Asset issued in the given funding round',
+  })
+  @ApiParam({
+    name: 'asset',
+    description: 'The Asset (Ticker/Asset ID) whose issued amount is to be fetched',
+    type: 'string',
+    example: '3616b82e-8e10-80ae-dc95-2ea28b9db8b3',
+  })
+  @ApiParam({
+    name: 'round',
+    description: 'The name of the funding round',
+    type: 'string',
+    example: 'Series A',
+  })
+  @ApiOkResponse({
+    description: 'The total amount of the Asset issued in the funding round',
+    type: IssuedInFundingRoundModel,
+  })
+  @Get(':asset/funding-rounds/:round/issued')
+  public async getIssuedInFundingRound(
+    @Param() { asset, round }: FundingRoundParamsDto
+  ): Promise<IssuedInFundingRoundModel> {
+    const issued = await this.assetsService.getIssuedInFundingRound(asset, round);
+
+    return new IssuedInFundingRoundModel({ fundingRound: round, issued });
+  }
+
   @ApiOperation({
     summary: 'Add required mediators',
     description:

src/assets/assets.service.spec.ts

@@ -808,6 +808,21 @@ describe('AssetsService', () => {
     });
   });
 
+  describe('getIssuedInFundingRound', () => {
+    it('should return the amount issued in the funding round', async () => {
+      const mockAsset = new MockAsset();
+      mockAsset.getIssuedInFundingRound.mockResolvedValue(new BigNumber(1000));
+
+      const findOneSpy = jest.spyOn(service, 'findOne');
+      findOneSpy.mockResolvedValue(mockAsset as unknown as FungibleAsset);
+
+      const result = await service.getIssuedInFundingRound('TICKER', 'Series A');
+
+      expect(result).toEqual(new BigNumber(1000));
+      expect(mockAsset.getIssuedInFundingRound).toHaveBeenCalledWith('Series A');
+    });
+  });
+
   describe('addRequiredMediators', () => {
     it('should run a addRequiredMediators procedure and return the transaction results', async () => {
       const mockTransaction = setupMockTransaction(

src/assets/assets.service.ts

@@ -10,6 +10,7 @@ import {
   HistoricAgentOperation,
   Identity,
   IdentityBalance,
+  Instruction,
   NftCollection,
   ResultSet,
   TransferRestrictionParams,
@@ -265,7 +266,7 @@ export class AssetsService {
     );
   }
 
-  public async transferFunds(params: TransferFundsDto): ServiceReturn<void> {
+  public async transferFunds(params: TransferFundsDto): ServiceReturn<Instruction | undefined> {
     const { options, args } = extractTxOptions(params);
     const { from, to, asset, amount, nfts, memo } = args;
 
@@ -323,6 +324,14 @@ export class AssetsService {
     });
   }
 
+  public async getIssuedInFundingRound(
+    assetInput: string,
+    fundingRound: string
+  ): Promise<BigNumber> {
+    const asset = await this.findOne(assetInput);
+    return asset.getIssuedInFundingRound(fundingRound);
+  }
+
   public async addRequiredMediators(
     assetInput: string,
     params: RequiredMediatorsDto

src/assets/dto/funding-round-params.dto.ts

@@ -0,0 +1,10 @@
+/* istanbul ignore file */
+
+import { IsString } from 'class-validator';
+
+import { AssetParamsDto } from '~/assets/dto/asset-params.dto';
+
+export class FundingRoundParamsDto extends AssetParamsDto {
+  @IsString()
+  readonly round: string;
+}