feat(packages/jellyfish-api-core): Add waitForBlock RPC

docs/node/CATEGORIES/01-blockchain.md

@@ -432,6 +432,21 @@ interface WaitBlockResult {
 }
 ```
 
+## waitForBlock
+
+Waits for a specific new block and returns useful info about it.
+
+```ts title="client.blockchain.waitForBlock()"
+interface blockchain {
+  waitForBlock (blockhash: string, timeout: number = 30000): Promise<WaitBlockResult>
+}
+
+interface WaitBlockResult {
+  hash: string
+  height: number
+}
+```
+
 ## waitForBlockHeight
 
 Waits for block height equal or higher than provided and returns the height and hash of the current tip.

packages/jellyfish-api-core/__tests__/category/blockchain/waitForBlock.test.ts

@@ -0,0 +1,69 @@
+import { MasterNodeRegTestContainer } from '@defichain/testcontainers'
+import { ContainerAdapterClient } from '../../container_adapter_client'
+import { TestingGroup } from '@defichain/jellyfish-testing'
+
+describe('Waits for a specific new block and returns useful info about it', () => {
+  const container = new MasterNodeRegTestContainer()
+  const client = new ContainerAdapterClient(container)
+
+  beforeAll(async () => {
+    await container.start()
+  })
+
+  afterAll(async () => {
+    await container.stop()
+  })
+
+  it('should wait for block', async () => {
+    {
+      const count = await client.blockchain.getBlockCount()
+      expect(count).toStrictEqual(0)
+    }
+
+    {
+      await container.generate(20)
+
+      const blockhash = await client.blockchain.getBlockHash(20)
+      const promise = client.blockchain.waitForBlock(blockhash)
+
+      await container.restart()
+
+      expect(await promise).toStrictEqual({
+        height: 20,
+        hash: blockhash
+      })
+
+      const count = await client.blockchain.getBlockCount()
+      expect(count).toStrictEqual(20)
+    }
+  })
+})
+
+describe('wait for block on multiple nodes', () => {
+  const group = TestingGroup.create(2)
+
+  beforeAll(async () => {
+    await group.start()
+  })
+
+  afterAll(async () => {
+    await group.stop()
+  })
+
+  it('should wait for new block on another node', async () => {
+    await group.get(0).generate(2)
+
+    const blockhash = await group.get(0).rpc.blockchain.getBlockHash(2)
+
+    // hold on to await to resolve later
+    const promise = group.get(1).rpc.blockchain.waitForBlock(blockhash)
+
+    expect(await promise).toStrictEqual({
+      height: 2,
+      hash: blockhash
+    })
+
+    const count = await group.get(1).rpc.blockchain.getBlockCount()
+    expect(count).toStrictEqual(2)
+  })
+})

packages/jellyfish-api-core/src/category/blockchain.ts

@@ -254,6 +254,17 @@ export class Blockchain {
     return await this.client.call('waitfornewblock', [timeout], 'number')
   }
 
+  /**
+   * Waits for a specific new block and returns useful info about it.
+   *
+   * @param {string} blockhash Block hash to wait for.
+   * @param {number} [timeout=30000] in millis
+   * @return Promise<WaitBlockResult> the current block on timeout or exit
+   */
+  async waitForBlock (blockhash: string, timeout: number = 30000): Promise<WaitBlockResult> {
+    return await this.client.call('waitforblock', [blockhash, timeout], 'number')
+  }
+
   /**
    * Waits for block height equal or higher than provided and returns the height and hash of the current tip.
    *