feat(sdk): add NFT actions in the JS Dash SDK

packages/js-dash-sdk/docs/platform/documents/broadcast.md

@@ -3,13 +3,17 @@
 
 Parameters: 
 
-| parameters                 | type       | required | Description                                                                  |  
-|----------------------------|------------|----------|------------------------------------------------------------------------------|
-| **documents**              | Object     | yes      |                                                                              |
-| **documents.create**       | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to create |
-| **documents.replace**      | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to replace         |
-| **documents.delete**       | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to delete          |
-| **identity**               | Identity   | yes      | A valid [registered identity](../identities/register.md)                     |
+| parameters                | type               | required | Description                                                                            |  
+|---------------------------|--------------------|----------|----------------------------------------------------------------------------------------|
+| **documents**             | Object             | yes      |                                                                                        |
+| **documents.create**      | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to create                    |
+| **documents.replace**     | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to replace                   |
+| **documents.delete**      | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to delete                    |
+| **documents.transfer**    | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to transfer                  |
+| **documents.updatePrice** | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to set price                 |
+| **documents.purchase**    | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to purchase                  |
+| **identity**              | Identity           | yes      | A valid [registered identity](../identities/register.md)                               |
+| **options**               | DocumentTransitionParams           | no       | An object with two optional fields `price` and `receiver` that is used for NFT actions |
 
 
 **Example**:

packages/js-dash-sdk/docs/platform/documents/purchase.md

@@ -0,0 +1,33 @@
+**Usage**: `client.platform.documents.broadcast(documents, identity, options)`    
+**Description**: This method will broadcast a purchase state transition that buys the given document from other Identity.
+
+Parameters: 
+
+| parameters             | type    | required            | Description                                                       |  
+|------------------------|---------|------------------	|-------------------------------------------------------------------|
+| **documents.purchase** | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to buy  |
+| **identity**           | Identity | yes                 | A valid [registered identity](../identities/register.md)          |
+| **options**            | DocumentTransitionParams           | no       | An object with field `price` (BigInt) and `receiver` (Identifier) |
+
+**Example**: 
+```js
+const identityId = '';// Your identity identifier
+const receiverId = ''; // Receiver identity identifier
+const documentId = '' // Your document id
+const price = BigInt(1000000)
+
+const identity = await client.platform.identities.get(identityId);
+const receiverIdentity = await client.platform.identities.get(receiverId);
+
+const identity = await client.platform.identities.get(identityId);
+
+const [document] = await dash.platform.documents.get(
+  'helloWorldContract.note',
+  { where: [['$id', '==', documentId]] },
+);
+
+await dash.platform.documents.broadcast({ purchase: [document], }, identity, { price, receiver: receiverIdentity.getId() });
+```
+**Note**: This method will change the ownership of the document to your identity, and seller identity will be credited with the amount specified in the updatePrice deducted from your balance.
+
+Returns: DocumentsBatchTransition

packages/js-dash-sdk/docs/platform/documents/transfer.md

@@ -0,0 +1,31 @@
+**Usage**: `client.platform.documents.broadcast(documents, identity, options)`    
+**Description**: This method will broadcast a document transfer
+
+Parameters: 
+
+| parameters        | type    | required            | Description                                                           |  
+|-------------------|---------|------------------	|-----------------------------------------------------------------------|
+| **documents.transfer**    | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to transfer |
+| **identity**      | Identity | yes                 | A valid [registered identity](../identities/register.md)              |
+| **options**               | DocumentTransitionParams           | no       | An object with `receiver` field                                       |
+
+**Example**: 
+```js
+const identityId = '';// Your identity identifier
+const receiverId = ''; // Receiver identity identifier
+const documentId = '' // Your document id
+
+const identity = await client.platform.identities.get(identityId);
+const receiverIdentity = await client.platform.identities.get(receiverId);
+
+const [document] = await dash.platform.documents.get(
+  'helloWorldContract.note',
+  { where: [['$id', '==', documentId]] },
+);
+
+await dash.platform.documents.broadcast({ transfer: [document], }, identity, { receiver: receiverIdentity.getId() });
+```
+
+**Note**: Transfer transition changes the ownership of the given document to the receiver identity  
+
+Returns: DocumentsBatchTransition

packages/js-dash-sdk/docs/platform/documents/updatePrice.md

@@ -0,0 +1,29 @@
+**Usage**: `client.platform.documents.broadcast(documents, identity, options)`    
+**Description**: This method will broadcast an update price state transition that sets a price for the given document.
+
+Parameters: 
+
+| parameters                | type    | required            | Description                                                               |  
+|---------------------------|---------|------------------	|---------------------------------------------------------------------------|
+| **documents.updatePrice** | ExtendedDocument[] | no       | array of valid [created document](../documents/create.md) to update price |
+| **identity**              | Identity | yes                 | A valid [registered identity](../identities/register.md)                  |
+| **options**               | DocumentTransitionParams           | no       | An object with field `price` (BigInt)                                     |
+
+**Example**: 
+```js
+const identityId = '';// Your identity identifier
+const documentId = '' // Your document id
+const price = BigInt(1000000)
+
+const identity = await client.platform.identities.get(identityId);
+
+const [document] = await dash.platform.documents.get(
+  'helloWorldContract.note',
+  { where: [['$id', '==', documentId]] },
+);
+
+await dash.platform.documents.broadcast({ updatePrice: [document], }, identity, { price });
+```
+**Note**: This method sets the same price on all documents in the batch (only one is possible right now)
+
+Returns: DocumentsBatchTransition

packages/js-dash-sdk/src/SDK/Client/Client.spec.ts

@@ -313,7 +313,7 @@ describe('Dash - Client', function suite() {
       let error;
       try {
         await client.platform.documents.broadcast({
-          create: documentsFixture,
+          create: documentsFixture.map((d) => ({ document: d, params: null })),
         }, identityFixture);
       } catch (e) {
         error = e;
@@ -332,7 +332,7 @@ describe('Dash - Client', function suite() {
       dapiClientMock.platform.waitForStateTransitionResult.resolves(proofResponse);
 
       await client.platform.documents.broadcast({
-        create: documentsFixture,
+        create: documentsFixture.map((d) => ({ document: d, params: null })),
       }, identityFixture);
 
       const serializedSt = dapiClientMock.platform.broadcastStateTransition.getCall(0).args[0];

packages/js-dash-sdk/src/SDK/Client/Platform/methods/documents/broadcast.ts

@@ -1,31 +1,49 @@
-import { ExtendedDocument } from '@dashevo/wasm-dpp';
+import { ExtendedDocument, Identifier } from '@dashevo/wasm-dpp';
 import { Platform } from '../../Platform';
 import broadcastStateTransition from '../../broadcastStateTransition';
 import { signStateTransition } from '../../signStateTransition';
 
+interface DocumentTransitionParams {
+  receiver?: Identifier;
+  price?: bigint;
+}
+
+interface DocumentSubmittable {
+  document: ExtendedDocument;
+  params?: DocumentTransitionParams;
+}
+
 /**
  * Broadcast document onto the platform
  *
- * @param {Platform} this - bound instance class
  * @param {Object} documents
- * @param {ExtendedDocument[]} [documents.create]
- * @param {ExtendedDocument[]} [documents.replace]
- * @param {ExtendedDocument[]} [documents.delete]
- * @param identity - identity
+ * @param {DocumentSubmittable[]} [documents.create]
+ * @param {DocumentSubmittable[]} [documents.replace]
+ * @param {DocumentSubmittable[]} [documents.delete]
+ * @param {DocumentSubmittable[]} [documents.transfer]
+ * @param {DocumentSubmittable[]} [documents.updatePrice]
+ * @param {DocumentSubmittable[]} [documents.purchase]
+ * @param {Identity} identity
  */
 export default async function broadcast(
   this: Platform,
   documents: {
-    create?: ExtendedDocument[],
-    replace?: ExtendedDocument[],
-    delete?: ExtendedDocument[]
+    create?: DocumentSubmittable[],
+    replace?: DocumentSubmittable[],
+    delete?: DocumentSubmittable[],
+    transfer?: DocumentSubmittable[],
+    updatePrice?: DocumentSubmittable[],
+    purchase?: DocumentSubmittable[],
   },
   identity: any,
 ): Promise<any> {
   this.logger.debug('[Document#broadcast] Broadcast documents', {
     create: documents.create?.length || 0,
     replace: documents.replace?.length || 0,
     delete: documents.delete?.length || 0,
+    transfer: documents.transfer?.length || 0,
+    updatePrice: documents.updatePrice?.length || 0,
+    purchase: documents.purchase?.length || 0,
   });
   await this.initialize();
 
@@ -36,20 +54,47 @@ export default async function broadcast(
     ...(documents.create || []),
     ...(documents.replace || []),
     ...(documents.delete || []),
-  ][0]?.getDataContractId();
+    ...(documents.transfer || []),
+    ...(documents.updatePrice || []),
+    ...(documents.purchase || []),
+  ][0]?.document.getDataContractId();
 
   if (!dataContractId) {
     throw new Error('Data contract ID is not found');
   }
 
+  if (documents.transfer?.length && documents.transfer
+    .some(({ params }) => !params?.receiver)) {
+    throw new Error('Receiver identity is not found for transfer transition');
+  }
+
+  if (documents.updatePrice?.length && documents.updatePrice
+    .some(({ params }) => !params?.price)) {
+    throw new Error('Price must be provided for UpdatePrice operation');
+  }
+
+  if (documents.purchase?.length) {
+    if (documents.purchase
+      .some(({ params }) => !params?.price || !params?.receiver)) {
+      throw new Error('Receiver and Price must be provided for UpdatePrice operation');
+    } else {
+      documents.purchase.forEach(({ document, params }) => document.setOwnerId(params!.receiver));
+    }
+  }
+
   const identityContractNonce = await this.nonceManager
     .bumpIdentityContractNonce(identityId, dataContractId);
 
-  const documentsBatchTransition = dpp.document.createStateTransition(documents, {
+  const identityNonceObj = {
     [identityId.toString()]: {
       [dataContractId.toString()]: identityContractNonce.toString(),
     },
-  });
+  };
+
+  const documentsBatchTransition = dpp.document.createStateTransition(
+    documents,
+    identityNonceObj,
+  );
 
   this.logger.silly('[Document#broadcast] Created documents batch transition');
 
@@ -61,15 +106,15 @@ export default async function broadcast(
   // Acknowledge documents identifiers to handle retry attempts to mitigate
   // state transition propagation lag
   if (documents.create) {
-    documents.create.forEach((document) => {
+    documents.create.forEach(({ document }) => {
       const documentLocator = `${document.getDataContractId().toString()}/${document.getType()}`;
       this.fetcher.acknowledgeKey(documentLocator);
     });
   }
 
   // Forget documents identifiers to not retry on them anymore
   if (documents.delete) {
-    documents.delete.forEach((document) => {
+    documents.delete.forEach(({ document }) => {
       const documentLocator = `${document.getDataContractId().toString()}/${document.getType()}`;
       this.fetcher.forgetKey(documentLocator);
     });
@@ -79,6 +124,7 @@ export default async function broadcast(
     create: documents.create?.length || 0,
     replace: documents.replace?.length || 0,
     delete: documents.delete?.length || 0,
+    transfer: documents.transfer?.length || 0,
   });
 
   return documentsBatchTransition;

packages/js-dash-sdk/src/SDK/Client/Platform/methods/names/register.ts

@@ -74,7 +74,7 @@ export async function register(
 
   await this.documents.broadcast(
     {
-      create: [preorderDocument],
+      create: [{ document: preorderDocument }],
     },
     identity,
   );
@@ -99,7 +99,7 @@ export async function register(
   // 4. Create and send domain state transition
   await this.documents.broadcast(
     {
-      create: [domainDocument],
+      create: [{ document: domainDocument }],
     },
     identity,
   );

packages/platform-test-suite/test/e2e/contacts.spec.js

@@ -145,7 +145,7 @@ describe('e2e', () => {
         });
 
         await bobClient.platform.documents.broadcast({
-          create: [profile],
+          create: [{ document: profile }],
         }, bobIdentity);
 
         // Additional wait time to mitigate testnet latency
@@ -244,7 +244,7 @@ describe('e2e', () => {
         });
 
         await aliceClient.platform.documents.broadcast({
-          create: [aliceProfile],
+          create: [{ document: aliceProfile }],
         }, aliceIdentity);
 
         // Additional wait time to mitigate testnet latency
@@ -265,7 +265,7 @@ describe('e2e', () => {
 
         // 2. Broadcast change
         await aliceClient.platform.documents.broadcast({
-          replace: [aliceProfile],
+          replace: [{ document: aliceProfile }],
         }, aliceIdentity);
 
         // Additional wait time to mitigate testnet latency
@@ -299,7 +299,7 @@ describe('e2e', () => {
         });
 
         await bobClient.platform.documents.broadcast({
-          create: [bobContactRequest],
+          create: [{ document: bobContactRequest }],
         }, bobIdentity);
 
         // Additional wait time to mitigate testnet latency
@@ -324,7 +324,7 @@ describe('e2e', () => {
         });
 
         await aliceClient.platform.documents.broadcast({
-          create: [aliceContactAcceptance],
+          create: [{ document: aliceContactAcceptance }],
         }, aliceIdentity);
 
         // Additional wait time to mitigate testnet latency
@@ -344,7 +344,7 @@ describe('e2e', () => {
       it('should be able to remove contact approval', async () => {
         // 1. Broadcast document deletion
         await aliceClient.platform.documents.broadcast({
-          delete: [aliceContactAcceptance],
+          delete: [{ document: aliceContactAcceptance }],
         }, aliceIdentity);
 
         // Additional wait time to mitigate testnet latency

packages/platform-test-suite/test/e2e/dpns.spec.js

@@ -260,7 +260,7 @@ describe('DPNS', () => {
 
       try {
         await client.platform.documents.broadcast({
-          delete: [registeredDomain],
+          delete: [{ document: registeredDomain }],
         }, identity);
       } catch (e) {
         broadcastError = e;

packages/platform-test-suite/test/e2e/withdrawals.spec.js

@@ -114,7 +114,7 @@ describe('Withdrawals', function withdrawalsTest() {
 
       // Should allow deleting of the withdrawal document
       await client.platform.documents.broadcast({
-        delete: [withdrawalDocument],
+        delete: [{ document: withdrawalDocument }],
       }, identity);
     });
 
@@ -216,7 +216,7 @@ describe('Withdrawals', function withdrawalsTest() {
 
       try {
         await client.platform.documents.broadcast({
-          create: [withdrawal],
+          create: [{ document: withdrawal }],
         }, identity);
 
         expect.fail('should throw broadcast error');
@@ -260,7 +260,7 @@ describe('Withdrawals', function withdrawalsTest() {
 
       try {
         await client.platform.documents.broadcast({
-          delete: [withdrawalDocument],
+          delete: [{ document: withdrawalDocument }],
         }, identity);
 
         expect.fail('should throw broadcast error');
@@ -283,7 +283,7 @@ describe('Withdrawals', function withdrawalsTest() {
 
       try {
         await client.platform.documents.broadcast({
-          replace: [withdrawalDocument],
+          replace: [{ document: withdrawalDocument }],
         }, identity);
 
         expect.fail('should throw broadcast error');