@qrkit/bc-ur 2.0.0-beta.9-qrkit.1

package/src/classes/FountainEncoder.ts

@@ -0,0 +1,211 @@
+import { chooseFragments, findNominalFragmentLength, mixFragments, partitionMessage } from "../helpers/fountainUtils.js";
+import { toUint32, getCRC } from "../helpers/utils.js";
+import { CborEncoding } from "../encodingMethods/CborEncoding.js";
+
+const cborEncoder = new CborEncoding();
+
+/** [seqNum, seqLength, messageLength, checksum, fragment] */
+export type IMultipartUrPayload = [number, number, number, number, Uint8Array];
+
+/**
+ * Encode data on the fly. This encoder uses an internal state to keep generating ur fragments of the payload.
+ */
+export class FountainEncoder {
+  public fragmentLenghtFinder = findNominalFragmentLength;
+
+  /** Total data size of the input message */
+  public _messageLength: number;
+  /** Maximum data size in the fragment */
+  protected _maxFragmentLength: number;
+  /** Minumum data size in the fragment */
+  protected _minFragmentLength: number;
+  /** Calculated data size in the fragment */
+  public _nominalFragmentLength: number;
+  /** Array of pure fragments (without any fountain encoded) */
+  public _pureFragments: Uint8Array[];
+  /** Current index of the fragment start from 1 */
+  protected _seqNum: number;
+  /** Checksum of the original data */
+  protected _checksum: number;
+  /** Original Input data as UR */
+  protected _input: Uint8Array;
+
+  constructor(
+    input: Uint8Array,
+    maxFragmentLength: number = 100,
+    minFragmentLength: number = 10,
+    firstSeqNum: number = 0
+  ) {
+
+
+    // Validate the input
+    if (!input) {
+      throw new Error("input should be defined");
+    }
+
+    if(!(input instanceof Uint8Array)) {
+      throw new Error("input should be Uint8Array")
+    }
+
+    if (typeof maxFragmentLength !== "number") {
+      throw new Error("maxFragmentLength should be a number");
+    }
+
+    if (typeof minFragmentLength !== "number") {
+      throw new Error("minFragmentLength should be a number");
+    }
+
+    if (typeof firstSeqNum !== "number") {
+      throw new Error("firstSeqNum should be a number");
+    }
+
+    if (maxFragmentLength < 1) {
+      throw new Error("maxFragmentLength should be > 0");
+    }
+
+    if(maxFragmentLength < minFragmentLength) {
+      throw new Error("maxFragmentLength should be >= minFragmentLength");
+    } 
+
+
+    this._input = input;
+    this._maxFragmentLength = maxFragmentLength;
+    this._minFragmentLength = minFragmentLength;
+    this._seqNum = toUint32(firstSeqNum);
+    
+    // Get the length of the message
+    this._messageLength = input.length;
+
+    // Check if message is less than maxFragmentLength, then return the message as a single fragment
+    if (input.length <= maxFragmentLength) {
+      this._pureFragments = [input];
+      this._nominalFragmentLength = this._messageLength;
+    }
+    // Otherwise calciulate the nominal fragment length and neseccary fragments
+    else {
+      // Check for the nominal length of a fragment.
+      const fragmentLength = this.fragmentLenghtFinder(input.length, maxFragmentLength, minFragmentLength);
+      this._nominalFragmentLength = fragmentLength;
+      // Calculate the checksum of the message
+      this._checksum = getCRC(input);
+      // Split up the message buffer in an array of buffers, by the nominal length
+      this._pureFragments = partitionMessage(input, fragmentLength);
+    }   
+  }
+
+  setFragmentLengthFinder(fn: typeof findNominalFragmentLength) {
+    this.fragmentLenghtFinder = fn;
+  }  
+
+  /**
+   * Return all the fragments based on the fountain ratio at once as an array of Uint8Arrays.
+   * @param fountainRatio The ratio of the fountain fragments to the pure fragments. Default is 0.
+   * @returns 
+   */
+  getAllParts(fountainRatio: number = 0): Uint8Array[] {
+    // First check if the input is a single fragment
+    if (this.isSinglePart()) {
+      return [this._input];
+    }
+    // Ceil to always get an integer
+    const numberofParts = Math.ceil(this.getPureFragmentCount() * (1 + fountainRatio));
+    // Save state
+    const oldSeqNum = this._seqNum;
+    // Reset state to start generating fragments from the beginning
+    this._seqNum = 0;
+    // Generate fragments
+    let fragments = []
+    for (let i = 0; i < numberofParts; i++) {
+      fragments.push(this.nextPart());
+    }
+    // Bring state back
+    this._seqNum = oldSeqNum;
+    return fragments;
+  }
+
+  // Encode fragment with correct CBOR structure
+  protected encodeFragment(seqNum:number, fragment:Uint8Array): Uint8Array {
+    // Shape for the CBOR payload
+    const payload: IMultipartUrPayload = [seqNum, this._pureFragments.length, this._messageLength, this._checksum, fragment];
+    const encodedFragment = cborEncoder.encode(payload);
+
+    return encodedFragment;
+  }
+
+  /**
+   * Reset the state of the encoder to start generating fragments from the beginning.
+   */
+  public reset() {
+    this._seqNum = 0;
+  }
+
+
+  /**
+   * Checks if all the pure fragments (full payload data) for this ur is generated.
+   * @returns boolean indicating if generated fragments have included all the data.
+   */
+  public isComplete(): boolean {
+    return this._seqNum >= this.getPureFragmentCount();
+  }
+
+  /**
+   * Checks if there is only one fragment generated for the ur.
+   * @returns boolean if the ur payload is contained in one fragment.
+   */
+  public isSinglePart(): boolean {
+    return this.getPureFragmentCount() === 1;
+  }
+
+  /**
+   * Gets the count of the "pure" fragments. These are fragments where the data is not mixed.
+   * @returns The count of the "pure" fragments.
+   */
+  public getPureFragmentCount(): number {
+    return this._pureFragments.length;
+  }
+
+  /**
+   * Get the pure fragments of the ur.
+   * @returns the pure fragments of the ur as an array of Uint8Arrays.
+   */
+  public getPureFragments(): Uint8Array[] {
+    return this._pureFragments;
+  }
+
+  /**
+   * Give the 'next' fragment for the ur for which the fountainEncoder was created.
+   * @returns the 'next' fragment, represented as a Ur multipart string.
+   */
+  public nextPart(): Uint8Array {
+    this._seqNum = toUint32(this._seqNum + 1);
+    
+    // when the seqnum restarts because of a number bigger than Uint32, we need to make sure to skip 0 to prevent invalid Multipart URs.
+    if (this._seqNum === 0) {
+      this._seqNum = toUint32(this._seqNum + 1);
+    }
+    
+    // If its single part, return the original input
+    if (this.isSinglePart()) {
+      return this._input;
+    }
+    
+    // For the first seqNum of the pure fragments, return the pure fragment
+    if (!this.isComplete()) {
+      return this.encodeFragment(this._seqNum, this._pureFragments[this._seqNum - 1]);
+    }
+
+    // For the fountain fragments, mix the fragments
+    const indexes = chooseFragments(
+      this._seqNum,
+      this._pureFragments.length,
+      this._checksum
+    );
+    const mixed = mixFragments(
+      indexes,
+      this._pureFragments,
+      this._nominalFragmentLength
+    );
+
+    return this.encodeFragment(this._seqNum, mixed);
+  }
+}

package/src/classes/RegistryItem.ts

@@ -0,0 +1,240 @@
+import { UR } from "./UR.js";
+import { encodeKeys, decodeKeys, IKeyMap } from "./key.helper.js";
+
+// Define the symbol
+export const registryItemSymbol = Symbol.for("RegistryItemBase");
+
+/**
+ * Static interface that RegistryItem classes should implement
+ */
+export interface IRegistryType {
+  /**
+   * Cbor Tags
+   * Finalized versions defined in: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml
+   */
+  tag: number;
+  /**
+   * Uniform Resource ID
+   *
+   * Links:
+   * - https://developer.blockchaincommons.com/ur/
+   * - https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-006-urtypes.md
+   * - https://github.com/ngraveio/Research
+   * - https://github.com/KeystoneHQ/Keystone-developer-hub/tree/main/research
+   *
+   */
+  URType: string;
+  /** CDDL definition for CBOR encoding */
+  CDDL: string;
+  /** Key name to key in integer map for smaller encoded data size */
+  keyMap?: IKeyMap;
+  /** allow the keys that are not explicitely defined in the keyMap */
+  allowKeysNotInMap?: boolean;
+}
+
+export abstract class RegistryItemBase {
+  readonly type: IRegistryType;
+  /** If CDDL contains keys as numbers, map them to their respective values */
+  keyMap: IKeyMap;
+  /** Data that our item contains */
+  // TODO: should we force this to be a map? It is much safer that way for injection attacks
+  data: any;
+  static allowKeysNotInMap: any;
+
+  constructor(registryType: IRegistryType, data?: any, keyMap?: IKeyMap) {
+    this.type = registryType;
+    this.keyMap = keyMap;
+
+    // Verify input
+    const { valid, reasons } = this.verifyInput(data);
+    if (!valid) {
+      throw new Error(`Invalid input: ${reasons?.map((r) => r.message).join(", ")}`);
+    }
+    this.data = data;
+    (this as any)[registryItemSymbol] = true;
+  }
+
+  /**
+   * Verify the input data
+   *
+   * @param input
+   */
+  verifyInput(input: any): { valid: boolean; reasons?: Error[] } {
+    // This should be implemented by the child class
+    return {
+      valid: true,
+      reasons: undefined,
+    };
+  }
+
+  toString(): string {
+    return `${this.type.URType}[${this.type.tag}](${JSON.stringify(this.data)})`;
+  }
+
+  toJSON() {
+    // TODO: if there is any registry item in the data (could be nested or in array), we should call toJSON on them as well
+    return {
+      type: this.type.URType,
+      tag: this.type.tag,
+      ...this.data,
+    };
+  }
+
+  /**
+   * Preprocess the data before encoding into CBOR Tagged instance
+   *
+   * @param data, data before keymap conversion, if left empty, it will use the this.data property
+   */
+  preCBOR(data = this.data) {
+    // If key-map exists, convert keys to integers
+    if (this.keyMap) {
+      const allowKeysNotInMap = (this.constructor as typeof RegistryItemBase).allowKeysNotInMap;
+      return encodeKeys(data, this.keyMap, allowKeysNotInMap);
+    }
+    return data;
+  }
+
+  /**
+   * Called by the CBOR encoder for encoding the data
+   *
+   * [CBOR Docs](https://github.com/hildjj/cbor2?tab=readme-ov-file#tocbor-method)
+   *
+   * This is the easiest approach, if you can modify the class being encoded.
+   * Add a toCBOR() method to your class, which should return a two-element array containing the tag number and data item that encodes your class.
+   * If the tag number is NaN, no tag will be written. If you return undefined, nothing will be written.
+   * In this case you will likely write custom bytes to the Writer instance that is passed in,
+   * perhaps using the encoding options.
+   *
+   * @param encoder
+   * @returns
+   */
+  toCBOR(_writer, _options) {
+    const processed = this.preCBOR(this.data);
+    let tag = this.type.tag;
+    // TODO: find a better way to ignore top level tag on encoder
+    if (_options?.ignoreTopLevelTag) {
+      tag = NaN; // Do not tag the top level item
+      // Set it back to false for child items
+      _options.ignoreTopLevelTag = false;
+    }
+    return [tag, processed];
+  }
+
+  toUr() {
+    return new UR(this);
+  }
+
+  toHex() {
+    return this.toUr().getPayloadHex();
+  }
+
+  toBytes() {
+    return this.toUr().getPayloadCbor();
+  }
+
+  public encodeKeys = encodeKeys;
+  public decodeKeys = decodeKeys;
+
+  // Custom inspection method for Node.js
+  public [Symbol.for("nodejs.util.inspect.custom")](
+    _depth: number,
+    inspectOptions: object,
+    inspect: (val: unknown, opts: object) => unknown
+  ): string {
+    return `${this.type.URType}[${this.type.tag}](${inspect(this.data, inspectOptions)})`;
+  }
+}
+
+/**
+ * Factory function to create a new RegistryItem class
+ *
+ * It injects static properties to the class and does preprocessing when needed
+ *
+ * @param input
+ * @returns
+ */
+export function registryItemFactory<T extends RegistryItemBase>(input: IRegistryType): RegistryItemClass<T> {
+  const { tag, URType, CDDL, keyMap, allowKeysNotInMap = true } = input;
+  const _keyMap = keyMap;
+
+  return class extends RegistryItemBase {
+    // Add static properties to the class
+    static tag: number = tag;
+    static URType: string = URType;
+    static CDDL: string = CDDL;
+    static keyMap: IKeyMap = _keyMap;
+    static allowKeysNotInMap: boolean = allowKeysNotInMap;
+
+    // Initiate base class with the values
+    constructor(data?: any, keyMap: IKeyMap = _keyMap) {
+      super(input, data, keyMap);
+    }
+
+    /**
+     * Post process the data after decoding CBOR
+     */
+    static postCBOR(val: any, allowKeysNotInMapOverwrite?: boolean) {
+      // If key-map exists, convert integer keys back to string keys
+      if (keyMap) {
+        return decodeKeys(val, keyMap, allowKeysNotInMapOverwrite ?? allowKeysNotInMap);
+      }
+      return val;
+    }
+
+    static fromUr(ur: UR | string): T {
+      const urObj = typeof ur === "string" ? UR.fromString(ur) : ur;
+      const decoded = urObj.decode() as unknown;
+
+      return decoded as T;
+    }
+
+    static fromHex(hex: string): T {
+      const ur = UR.fromHex({ type: URType, payload: hex });
+      const decoded = ur.decode() as unknown;
+
+      return decoded as T;
+    }
+
+    /**
+     * Static method to create an instance from CBOR DataItem data.
+     * It processes the raw CBOR data if needed and returns a new instance of the class.
+     */
+    static fromCBORData(val: any, allowKeysNotInMap?: boolean, tagged?: any) {
+      // Do some post processing data coming from the cbor decoder
+      const data = this.postCBOR(val, allowKeysNotInMap);
+
+      // Return an instance of the generated class
+      return new this(data);
+    }
+
+  } as RegistryItemClass<T>;
+}
+
+// Helper type to define the RegistryItem class with custom constructors and static properties
+export type RegistryItemClass<T extends RegistryItemBase = RegistryItemBase> = {
+  new (...args: any[]): T;
+  tag: number;
+  URType: string;
+  CDDL: string;
+  keyMap?: IKeyMap;
+  allowKeysNotInMap: boolean;
+  postCBOR(val: any, allowKeysNotInMapOverwrite?: boolean): any;
+  fromCBORData(val: any, allowKeysNotInMap?: boolean, tagged?: any): T;
+  fromUr(ur: UR | string): T;
+  fromHex(hex: string): T;
+};
+export type RegistryItem = InstanceType<RegistryItemClass>;
+
+/**
+ * Function to check if an object is an instance of RegistryItemBase or its subclasses
+ * @param obj - The object to check
+ * @returns true if the object is an instance of RegistryItemBase or its subclasses
+ */
+export function isRegistryItem(obj: any): obj is RegistryItem {
+  return (
+    obj instanceof RegistryItemBase ||
+    (obj && obj[registryItemSymbol] === true) ||
+    //(obj && typeof obj.toCBOR === 'function' && typeof obj.toUr === 'function' && typeof obj.toHex === 'function' && typeof obj.toBytes === 'function' && obj.type !== undefined && obj.data !== undefined)
+    (obj && typeof obj.toCBOR === 'function' && typeof obj.toUr === 'function' && typeof obj.toHex === 'function' && obj.type !== undefined && obj.data !== undefined)
+  );
+}