Release all changes to master

.dockerignore

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

.github/workflows/build-publish-image.yml

@@ -0,0 +1,68 @@
+name: Build and publish image to Docker Hub and ECR
+
+on:
+  push:
+    tags:
+      - v*
+
+permissions:
+  id-token: write
+  contents: read
+
+env:
+  AWS_REGION: us-west-2
+  ECR_REPOSITORY: polymesh/polymesh-rest-api
+
+jobs:
+  publish:
+    name: Build and push image
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+
+      - name: Set package version
+        run: ./scripts/set-package-version.sh
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        with:
+          username: ${{ secrets.ASSOCIATION_DOCKER_USERNAME }}
+          password: ${{ secrets.ASSOCIATION_DOCKER_TOKEN }}
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@254c19bd240aabef8777f48595e9d2d7b972184b # v6.2.1
+        with:
+          role-to-assume: ${{ vars.ECR_PUSH_ROLE_ARN }}
+          aws-region: ${{ env.AWS_REGION }}
+
+      - name: Log in to Amazon ECR
+        id: ecr-login
+        uses: aws-actions/amazon-ecr-login@d539f0932e70871a027e9d5a9d8fc38589180a64 # v2.1.6
+
+      - name: Extract metadata (tags, labels) for Docker Hub
+        id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+        with:
+          images: ${{ secrets.ASSOCIATION_DOCKER_HUB_REPO }}
+
+      - name: Build and push image
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          provenance: true
+          sbom: true
+          tags: |
+            ${{ steps.meta.outputs.tags }}
+            ${{ steps.ecr-login.outputs.registry }}/${{ env.ECR_REPOSITORY }}:${{ github.ref_name }}
+            ${{ steps.ecr-login.outputs.registry }}/${{ env.ECR_REPOSITORY }}:${{ github.sha }}
+          labels: ${{ steps.meta.outputs.labels }}

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
 
@@ -65,6 +65,7 @@ $ yarn test:cov
 PORT=## port in which the server will listen. Defaults to 3000 ##
 POLYMESH_NODE_URL=## websocket URL for a Polymesh node ##
 POLYMESH_MIDDLEWARE_V2_URL=## URL for an instance of the Polymesh GraphQL Middleware Native SubQuery service ##
+POLYMESH_MIDDLEWARE_V2_API_KEY=## optional API key for the Middleware V2 GraphQL service, if it requires authentication ##
 POLYMESH_MIDDLEWARE_URL=## URL for an instance of the Polymesh GraphQL Middleware service @deprecated in favour of POLYMESH_MIDDLEWARE_V2_URL##
 POLYMESH_MIDDLEWARE_API_KEY=## API key for the Middleware GraphQL service ##
 LOCAL_SIGNERS=## list of comma separated IDs to refer to the corresponding mnemonic ##
@@ -73,7 +74,7 @@ LOCAL_MNEMONICS=## list of comma separated mnemonics for the signer service (eac
 # Below are optional params that enable some features. The above should be good to get started with
 
 DEVELOPER_SUDO_MNEMONIC=## a mnemonic that has `sudo` privileges for a chain. Defaults to `//Alice` ##
-DEVELOPER_UTILS=## set to `true` to enable developer testing endpoints ##
+DEVELOPER_UTILS=## set to `true` to enable developer testing endpoints. Never enable this in production ##
 
 # Vault Signer:
 VAULT_URL=## The URL of a Vault transit engine##
@@ -93,6 +94,8 @@ NOTIFICATIONS_LEGITIMACY_SECRET=## A secret used to create HMAC signatures ##
 # Auth:
 AUTH_STRATEGY=## list of comma separated auth strategies to use e.g. (`apiKey,open`) ##
 API_KEYS=## list of comma separated api keys to initialize the `apiKey` strategy with ##
+AUTH_MANAGEMENT_ENABLED=## `true` or `false` to expose the user and API key management endpoints (`/users/create`, `/auth/api-key/*`). Defaults to `false` when `AUTH_STRATEGY` includes `open`, otherwise `true` ##
+SIGNER_MANAGEMENT_ENABLED=## `true` or `false` to expose the endpoint that adds signing keys (`POST /signer`). Defaults to `false` when `AUTH_STRATEGY` includes `open`, otherwise `true` ##
 # Datastore:
 REST_POSTGRES_HOST=## Domain or IP of DB instance ##
 REST_POSTGRES_PORT=## Port the DB is listening (usually 5432) ##

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.1.0-beta.8",
+    "@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/app.module.ts

@@ -32,6 +32,7 @@ import { PolymeshModule } from '~/polymesh/polymesh.module';
 import { PortfoliosModule } from '~/portfolios/portfolios.module';
 import { ScheduleModule } from '~/schedule/schedule.module';
 import { SettlementsModule } from '~/settlements/settlements.module';
+import { SignerManagementModule } from '~/signing/signer-management.module';
 import { SigningModule } from '~/signing/signing.module';
 import { SubscriptionsModule } from '~/subscriptions/subscriptions.module';
 import { SubsidyModule } from '~/subsidy/subsidy.module';
@@ -47,6 +48,7 @@ import { UsersModule } from '~/users/users.module';
         POLYMESH_NODE_URL: Joi.string().required(),
         POLYMESH_MIDDLEWARE_URL: Joi.string(),
         POLYMESH_MIDDLEWARE_API_KEY: Joi.string(),
+        POLYMESH_MIDDLEWARE_V2_API_KEY: Joi.string(),
         SUBSCRIPTIONS_TTL: Joi.number().default(60000),
         SUBSCRIPTIONS_MAX_HANDSHAKE_TRIES: Joi.number().default(5),
         SUBSCRIPTIONS_HANDSHAKE_RETRY_INTERVAL: Joi.number().default(5000),
@@ -59,6 +61,8 @@ import { UsersModule } from '~/users/users.module';
         VAULT_URL: Joi.string().allow(''),
         DEVELOPER_SUDO_MNEMONIC: Joi.string().default('//Alice'),
         DEVELOPER_UTILS: Joi.bool().default(false),
+        AUTH_MANAGEMENT_ENABLED: Joi.bool(),
+        SIGNER_MANAGEMENT_ENABLED: Joi.bool(),
         API_KEYS: Joi.string().default(''),
         AUTH_STRATEGY: Joi.string().default(() => {
           if (process.env.NODE_ENV === 'production') {
@@ -97,8 +101,9 @@ import { UsersModule } from '~/users/users.module';
     NotificationsModule,
     ScheduleModule,
     NetworkModule,
-    AuthModule,
-    UsersModule,
+    AuthModule.register(),
+    UsersModule.register(),
+    SignerManagementModule.register(),
     DeveloperTestingModule.register(),
     MetadataModule,
     SubsidyModule,

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'];