feat!: mantaray 1.0

.github/workflows/ci.yaml

@@ -9,7 +9,7 @@ on:
       - '**'
 
 env:
-  BEE_VERSION: '1.1.0'
+  BEE_VERSION: '1.4.1'
   BLOCKCHAIN_VERSION: '1.2.0'
   BEE_ENV_PREFIX: 'swarm-test'
   BEE_IMAGE_PREFIX: 'docker.pkg.github.com/ethersphere/bee-factory'

README.md

@@ -1,19 +1,26 @@
 # Description
 
+The `mantaray` data-structure is widely used whithin the Swarm ecosystem; just to mention one, `manifests` are built on the mantaray data-structure, which consist of paths and file mappings of all dApps live on Ethereum Swarm.
+
 With this package you can manipulate and interpret mantaray data via `MantarayNode` and `MantarayFork` abstractions.
 
 # Exported Functions and Classes
 
 You can import the followings directly from `mantaray-js`:
 
+* MantarayV0_2        # legacy implementation of the mantaray data-structure, supported by the Bee client.
+* MantarayV1          # recent implementation of the mantaray data-structure, currently not supported by the Bee client. This codebase is the reference implementation for [the Mantaray 1.0 SWIP](https://github.com/ethersphere/SWIPs/pull/37).
+* initManifestNode    # initialize a manifest node (either `0.2` or `1.0`)
+* Utils               # all used utility functions in the library. Mostly operating on `Uint8Array` objects.
+* types*              # not callable, referring all types exported and reachable from the index
+
+The `MantarayV1` and `MantarayV0_2` versions have similar exposables:
+
 * MantarayNode        # class abstracting and manipulating Mantaray Node data
 * MantarayFork        # class abstracting and manipulating Mantaray Fork data
-* checkForSeparator   # checks for separator character in the node and its descendants prefixes
-* initManifestNode    # initialize a manifest node
 * loadAllNodes        # loads all mantaray nodes recursively from the storage
-* equalNodes          # checks whether the two given Mantaray Nodes objects are equal in the in-memory abstraction level
-* Utils               # all used utility functions in the library. Mostly operating on `Uint8Array` objects.
-* types*              # not callable, referring all types exported and reachable from the index
+* checkForSeparator   # _(only v0.2)_ checks for separator character in the node and its descendants prefixes
+* equalNodes          # _(only v0.2)_ checks whether the two given Mantaray Node objects are equal in the in-memory abstraction level
 
 # Basic usage
 
@@ -22,32 +29,46 @@ You can import the followings directly from `mantaray-js`:
 ```ts
 import { initManifestNode, Utils } from 'mantaray-js'
 
-const node = initManifestNode()
-const address1 = Utils.gen32Bytes() // instead of `gen32Bytes` some 32 bytes identifier that later could be retrieved from the storage
-const address2 = Utils.gen32Bytes()
-const address3 = Utils.gen32Bytes()
-const address4 = Utils.gen32Bytes()
-const address5 = Utils.gen32Bytes()
+const node = initManifestNode() // by default it gives back 1.0 version of Mantaray
+const address1 = Utils.hexToBytes<32>('4a07606f59562544dd37d26a219a65144e8cf3321b21276d8ea8de4af3ecee63')
+const address2 = Utils.hexToBytes<32>('0bf983d3bf7d46afad391856f302805cea6d1bdb2df0341a00ae29db42b1eb45')
+const address3 = Utils.hexToBytes<32>('5b5a1de0cdbf277446bdfc2b5f03ef12e5da8dfbd5d74ea608b0ff5544d584bd')
+const address4 = Utils.hexToBytes<32>('4f64abff074c90d37c82e3e21e4d18fee52eb887a8b163eab167248e1197459e')
+const address5 = Utils.hexToBytes<32>('0d7d218dfce224c1b53d7af8fd9cf88e7f053fe978716a768a88a853bd5f1bc7')
 const path1 = new TextEncoder().encode('path1/valami/elso')
 const path2 = new TextEncoder().encode('path1/valami/masodik')
 const path3 = new TextEncoder().encode('path1/valami/masodik.ext')
 const path4 = new TextEncoder().encode('path1/valami')
 const path5 = new TextEncoder().encode('path2')
-node.addFork(path1, address1)
-node.addFork(path2, address2, { vmi: 'elso' }) // here 'vmi' is a key of metadata and 'elso' is its value
-node.addFork(path3, address3)
-node.addFork(path4, address4, { vmi: 'negy' })
-node.addFork(path5, address5)
+node.addFork(path1, {
+    entry: address1, // keccak256 hash of any content that can be load from Storage. it acts as reference on the Path.
+})
+node.addFork(path2, {
+    entry: address2,
+    nodeMetadata: { vmi: 'elso' } // JSON metadata about the node that will be serialized on node level
+})
+node.addFork(path3, {
+    entry: address3, 
+    forkMetadata: { vmi2: 'masodik' } // JSON metadata about the node that will be serialized on fork level
+})
+node.addFork(path4, {
+    entry: address4,
+    nodeMetadata: { vmi3: '3' },
+    forkMetadata: { vmi3: 'harmadik', vmi: '3!' }
+})
+node.addFork(path5, {
+    nodeMetadata: { metadataAboutPath: 'it is not necessary to save entry for the new node' }
+})
 node.removePath(path3)
 // (...)
 ```
 
 ## Mantaray Storage Operations
 
 ```ts
-import { MantarayNode } from 'mantaray-js'
+import { MantarayV1 } from 'mantaray-js'
 
-const node = new MantarayNode()
+const node = new MantarayV1.MantarayNode()
 // here `reference` parameter is a `Reference` type which can be a 32 or 64 bytes Uint8Array
 // and `loadFunction` is a [loadFunction: async (address: Reference): Promise<Uint8Array>] typed function
 // that returns the serialised raw data of a MantarayNode of the given reference
@@ -68,9 +89,9 @@ The following describes the format of a node binary format.
 ┌────────────────────────────────┐
 │    obfuscationKey <32 byte>    │
 ├────────────────────────────────┤
-│ hash("mantaray:0.1") <31 byte> │
+│ hash("mantaray:1.0") <31 byte> │
 ├────────────────────────────────┤
-│     refBytesSize <1 byte>      │
+│      nodeFeatures <1 byte>     │
 ├────────────────────────────────┤
 │       entry <32/64 byte>       │
 ├────────────────────────────────┤
@@ -81,36 +102,27 @@ The following describes the format of a node binary format.
 │ ├────────────────────────────┤ │
 │ │            ...             │ │
 │ ├────────────────────────────┤ │
-│ │           Fork N           │ │
+│ │           Fork N           │ │ -> where N maximum is 256
 │ └────────────────────────────┘ │
+├────────────────────────────────┤
+│     nodeMetadata <varlen>      │
 └────────────────────────────────┘
 ```
 
 ## Fork
 
 ```
-┌───────────────────┬───────────────────────┬──────────────────┐
-│ nodeType <1 byte> │ prefixLength <1 byte> │ prefix <30 byte> │
-├───────────────────┴───────────────────────┴──────────────────┤
-│                    reference <32/64 bytes>                   │
-│                                                              │
+┌───────────────────────────────┬──────────────────────────────┐
+│     prefixLength <1 byte>     │        prefix <31 byte>      │
+├───────────────────────────────┴──────────────────────────────┤
+│                   reference <32/64 byte>                     │
+├──────────────────────────────────────────────────────────────┤
+│        forkMetadata <forkMetadataSegmentSize * 32 byte>      │
 └──────────────────────────────────────────────────────────────┘
 ```
 
-### Fork with metadata
-
-```
-┌───────────────────┬───────────────────────┬──────────────────┐
-│ nodeType <1 byte> │ prefixLength <1 byte> │ prefix <30 byte> │
-├───────────────────┴───────────────────────┴──────────────────┤
-│                    reference <32/64 bytes>                   │
-│                                                              │
-├─────────────────────────────┬────────────────────────────────┤
-│ metadataBytesSize <2 bytes> │     metadataBytes <varlen>     │
-├─────────────────────────────┘                                │
-│                                                              │
-└──────────────────────────────────────────────────────────────┘
-```
+If `forkMetadataSegmentSize` is 0, then `forkMetadata` is omitted.
+`forkMetadata` has the same length for each fork under one Mantaray node. 
 
 # Testing
 

jest.config.ts

@@ -1,31 +1,10 @@
-/* eslint-disable no-console */
 /*
  * For a detailed explanation regarding each configuration property and type check, visit:
  * https://jestjs.io/docs/en/configuration.html
  */
-import { BeeDebug } from '@ethersphere/bee-js'
 import type { Config } from '@jest/types'
 
 export default async (): Promise<Config.InitialOptions> => {
-  if (!process.env.BEE_POSTAGE) {
-    try {
-      console.log('Creating postage stamps...')
-      const beeDebugUrl = process.env.BEE_DEBUG_API_URL || 'http://localhost:1635'
-      const bee = new BeeDebug(beeDebugUrl)
-      process.env.BEE_POSTAGE = await bee.createPostageBatch('1', 20)
-      console.log('Queen stamp: ', process.env.BEE_POSTAGE)
-      // sleep for 11 seconds (10 blocks with ganache block time = 1s)
-      // needed for postage batches to become usable
-      // FIXME: sleep should be imported for this, but then we fail with
-      //        Could not find a declaration file for module 'tar-js'
-      await new Promise<void>(resolve => setTimeout(() => resolve(), 11_000))
-    } catch (e) {
-      // It is possible that for unit tests the Bee nodes does not run
-      // so we are only logging errors and not leaving them to propagate
-      console.error(e)
-    }
-  }
-
   return {
     // Indicates whether the coverage information should be collected while executing the test
     // collectCoverage: false,
@@ -47,5 +26,20 @@ export default async (): Promise<Config.InitialOptions> => {
 
     // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
     testPathIgnorePatterns: ['/node_modules/'],
+
+    // Run tests from one or more projects
+    projects: [
+      {
+        displayName: 'node:unit',
+        testEnvironment: 'node',
+        testRegex: 'test/unit/((?!\\.browser).)*\\.spec\\.ts',
+      },
+      {
+        displayName: 'node:integration',
+        testEnvironment: 'node',
+        testRegex: 'test/integration/((?!\\.browser).)*\\.spec\\.ts',
+        globalSetup: '<rootDir>/test/test-setup.ts'
+      },
+    ] as unknown[] as string[], // bad types
   }
 }