feat(cip2): initial implementation of RoundRobinRandomImprove

Author: mkazlauskas

Diff for: packages/cip2/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+secrets

Diff for: packages/cip2/README.md

@@ -0,0 +1,8 @@
+# Cardano JS SDK | CIP2 | Input Selection
+
+This package implements concepts from the draft specification being developed in [CIP-0002].
+
+Currently there is only 1 input selection algorithm: RoundRobinRandomImprove, which is a [Random-Improve] adaptation that handles asset selection.
+
+[cip-0002]: https://cips.cardano.org/cips/cip2/
+[random-improve]: https://cips.cardano.org/cips/cip2/#randomimprove

Diff for: packages/cip2/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@cardano-sdk/cip2",
+  "version": "0.1.0",
+  "description": "TypeScript definitions for CIP2 (Coin Selection Algorithms for Cardano)",
+  "engines": {
+    "node": "^14"
+  },
+  "main": "dist/index.js",
+  "repository": "https://github.com/input-output-hk/cardano-js-sdk/packages/cip2",
+  "author": "Martynas Kazlauskas <[email protected]>",
+  "license": "MPL-2.0",
+  "scripts": {
+    "build": "tsc --build ./src",
+    "tscNoEmit": "shx echo typescript --noEmit command not implemented yet",
+    "cleanup": "shx rm -rf dist node_modules",
+    "lint": "eslint --ignore-path ../../.eslintignore \"**/*.ts\"",
+    "test": "jest -c ./test/jest.config.js",
+    "test:debug": "DEBUG=true yarn test"
+  },
+  "devDependencies": {
+    "@cardano-ogmios/schema": "^4.0.0-beta.6",
+    "@emurgo/cardano-serialization-lib-nodejs": "^8.0.0",
+    "@types/lodash-es": "^4.17.5",
+    "fast-check": "^2.17.0",
+    "lodash": "^4.17.21",
+    "shx": "^0.3.3"
+  },
+  "dependencies": {
+    "@cardano-sdk/cardano-serialization-lib": "0.1.0",
+    "lodash-es": "^4.17.21"
+  }
+}

Diff for: packages/cip2/src/.eslintrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+  "extends": ["../../../.eslintrc.js"],
+  "parserOptions": {
+    "project": "./tsconfig.json",
+    "tsconfigRootDir": __dirname
+  }
+}

Diff for: packages/cip2/src/InputSelectionError.ts

@@ -0,0 +1,34 @@
+import { CustomError } from 'ts-custom-error';
+
+export enum InputSelectionFailure {
+  /**
+   * Total value of the entries within the initial UTxO set (the amount of money available)
+   * is less than the the total value of all entries in the requested output set (the amount of money required).
+   */
+  UtxoBalanceInsufficient = 'UTxO Balance Insufficient',
+  /**
+   * The number of entries in the initial UTxO set is smaller than the number of entries in the requested output set,
+   * for algorithms that impose the restriction that a single UTxO entry can only be used to pay for at most one output.
+   */
+  UtxoNotFragmentedEnough = 'UTxO Not Fragmented Enough',
+  /**
+   * The algorithm depletes all entries from the initial UTxO set
+   * before it is able to pay for all outputs in the requested output set.
+   * This can happen even if the total value of entries within the initial UTxO set
+   * is greater than the total value of all entries in the requested output set,
+   * due to various restrictions that coin selection algorithms impose on themselves when selecting UTxO entries.
+   */
+  UtxoFullyDepleted = 'UTxO Fully Depleted',
+  /**
+   * Another input must be selected by the algorithm in order to continue making progress,
+   * but doing so will increase the size of the resulting selection beyond an acceptable limit,
+   * specified by the maximum input count parameter.
+   */
+  MaximumInputCountExceeded = 'Maximum Input Count Exceeded'
+}
+
+export class InputSelectionError extends CustomError {
+  public constructor(public failure: InputSelectionFailure) {
+    super(failure);
+  }
+}