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

package/src/classes/UR.ts

@@ -0,0 +1,308 @@
+import { isRegistryItem, RegistryItem, RegistryItemBase } from "./RegistryItem.js";
+import { EncodingMethodName } from "../enums/EncodingMethodName.js";
+import { EncodingPipeline } from "../encodingMethods/pipeline.js";
+import {
+  InvalidPathLengthError,
+  InvalidSchemeError,
+  InvalidTypeError,
+} from "../errors.js";
+import { dataPipeline } from "../encodingMethods/index.js";
+import { ReplaceKeyType } from "../helpers/type.helper.js";
+
+export interface IUR {
+  type: string; // bc-ur type defined in the registry
+  payload: string; // encoded data
+  seqNum?: number; // sequence number if multipart starting with index 1 - if single part, this is 0
+  seqLength?: number; // total number of parts in the multipart message - if single part, this is 0
+  isFragment?: boolean; // if the ur is a fragment of a multipart message
+}
+
+/**
+ * https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-005-ur.md
+ * Class that represents the structure of the data we encode/decode in this package.
+ * e.g. 'ur:bytes/lpamcmcfatrdcyzcpldpgwhdhtiaiaecgyktgsflguhshthfghjtjngrhsfegtiafegaktgugui'
+ *
+ *
+ * Single part = ur:<type>/<message(payload)>
+ * Multi part =  ur:<type>/<seqNum-seqLength>/<fragment(payload)>
+ * 
+ * CBOR encoding should not include tag on top level when UR has a tag
+ * 
+ * I want to be able to create UR from encoding normal js types
+ * Or from any type in the pipeline
+ * 
+ * Should i do it on the encoder or ur class itself?
+ */
+export class UR {
+  public type: string;
+  public payload: string;
+  public seqNum?: number;
+  public seqLength?: number;
+  public isFragment: boolean;
+
+  static pipeline: EncodingPipeline<any, string> = dataPipeline;
+
+  // If type is unknown it should be cbor, because default encoding will take any and convert to cbor without tagging
+  constructor(input: IUR | RegistryItem) {
+    // Create from registry item
+    if (input instanceof RegistryItemBase || isRegistryItem(input)) {
+      const ur = UR.fromRegistryItem(input as RegistryItem);
+      this.type = ur.type;
+      this.payload = ur.payload;
+      this.seqNum = ur.seqNum;
+      this.seqLength = ur.seqLength;
+      this.isFragment = ur.isFragment;
+    } 
+    // Create from raw data
+    else if (typeof input == "object" && 'type' in input && 'payload' in input) {
+      const { type, payload, seqNum = 0, seqLength = 0 } = input;
+      this.payload = payload; 
+      this.type = type;
+      this.seqNum = seqNum;
+      this.seqLength = seqLength;
+      this.isFragment = seqLength > 0;
+    } 
+    else {
+      throw new InvalidTypeError();
+    }
+  }
+
+  // Decode
+  decode(until?: EncodingMethodName) {
+    return UR.pipeline.decode(this.payload, {until, enforceType: this.isFragment ? undefined : this.type});
+  }
+
+  // Get string representation
+  toString() {
+    return UR.getUrString(this.type, this.payload, this.seqNum, this.seqLength);
+  }
+
+  // Get payload in bytewords
+  getPayloadBytewords() {
+    return this.payload;
+  }
+
+  // Get payload in hex
+  getPayloadHex() {
+    return UR.pipeline.decode<string>(this.payload, { until: EncodingMethodName.hex });
+    // TODO: add tag information
+  }
+
+  // Get Payload in cbor
+  getPayloadCbor() {
+    return UR.pipeline.decode<Uint8Array>(this.payload, {until: EncodingMethodName.cbor} );
+    // TODO: add tag information
+  }
+
+  toRegistryItem() {
+    if (this.isFragment) {
+      throw new Error(
+        "Cannot convert a multipart ur to registry item, it needs to be decoded first"
+      );
+    }
+    // Enforce type
+    // registrtqueryByURType
+    return UR.decode(this);
+  }
+
+  /// Static methods
+
+  static fromRegistryItem(item: RegistryItem) {
+    // First convert Registry item to bytewords
+    // Only on the top level, we should not include the tag
+    const bytewords = UR.pipeline.encode(item, {ignoreTopLevelTag: true});
+
+    // Now create new UR
+    return new UR({
+      type: item.type.URType,
+      payload: bytewords,
+    });
+  }
+
+  /**
+   * Create UR from native javascript types by encoding them to bytewords
+   * @param input 
+   * @returns 
+   */
+  static fromData(input: ReplaceKeyType<IUR, 'payload', any>) {
+    const bytewords = UR.pipeline.encode(input.payload);
+
+    // Now create new UR
+    return new UR({
+      ...input,
+      payload: bytewords,
+    });    
+  }
+
+  static fromCbor(input: ReplaceKeyType<IUR, 'payload', Uint8Array>) {
+    // This means we already have cbor Uint8Array
+    // So we will start from the next method
+    const bytewords = UR.pipeline.encode(input.payload, { from: EncodingMethodName.hex });
+
+    return new UR({
+      ...input,
+      payload: bytewords,
+    });      
+  }
+
+  static fromHex(input: ReplaceKeyType<IUR, 'payload', string>) {
+    // This means we already have hex string
+    // So we will start from the next method
+    const bytewords = UR.pipeline.encode(input.payload, { from: EncodingMethodName.bytewords });
+
+    return new UR({
+      ...input,
+      payload: bytewords,
+    });    
+  }
+
+  static fromBytewords(input: IUR) {
+    return new UR({
+      ...input,
+    });    
+  }
+
+  static from(input: ReplaceKeyType<IUR, 'payload', any>, type: EncodingMethodName) {
+    switch (type) {
+      case EncodingMethodName.bytewords:
+        return UR.fromBytewords(input);
+      case EncodingMethodName.cbor:
+        return UR.fromCbor(input);
+      case EncodingMethodName.hex:
+        return UR.fromHex(input);
+      case EncodingMethodName.ur:
+        return UR.fromData(input);
+      default:
+        throw new Error("Invalid encoding method");
+    }
+  }
+
+  static fromString(ur: string) {
+    return new UR(UR.parseUr(ur));
+  }
+
+  static encode = this.fromRegistryItem;
+  static decode(ur: UR): RegistryItem {
+    // Force cbor type
+    return UR.pipeline.decode(ur.payload);
+  }
+
+  /**
+   * Check if the given string is a valid UR
+   * For single part ur, it should be in the form of "ur:<type>/<payload>" which is "ur:<lowercase letters, numbers or dashes>/<bytewords>"
+   * For multi part ur, it should be in the form of "ur:<type>/<seqNum-seqLength>/<fragment>" which is "ur:<lowercase letters, numbers or dashes>/<number-number>/<bytewords>"
+   * ur uses minimal bytewords encoding style which is a-z and has checksome bytes at the end
+   *
+   * @param input
+   * @returns
+   */
+  static validate(input: string): boolean {
+    // TODO: use bytewords encoding to validate the payload
+
+    const singlePartPattern = /^ur:[a-z0-9-]+\/[a-z]+$/;
+    const multiPartPattern = /^ur:[a-z0-9-]+\/[0-9]+-[0-9]+\/[a-z]+$/;
+
+    return singlePartPattern.test(input) || multiPartPattern.test(input);
+  }
+
+  /**
+   * Generates a UR string from the given type and payload.
+   * Single part = ur:<type>/<message(payload)> if seqNum and seqLength are 0
+   * Multi part =  ur:<type>/<seqNum-seqLength>/<fragment(payload)>
+   */
+  static getUrString(
+    type: string,
+    payload: string,
+    seqNum = 0,
+    seqLen = 0
+  ): string {
+    // Single UR
+    if (seqNum === 0 && seqLen === 0) {
+      return joinUri("ur", [type, payload]);
+    }
+
+    // Multi part UR
+    const seq = `${seqNum}-${seqLen}`;
+    return joinUri("ur", [type, seq, payload]);
+  }
+
+  /**
+   * Parses a UR and performs basic validation
+   * @param message e.g. "UR:BYTES/6-23/LPAMCHCFATTTCYCLEHGSDPHDHGEHFGHKKKDL..."
+   */
+  static parseUr(message: string): IUR {
+    const lowercase = message.toLowerCase(); // e.g. "ur:bytes/6-23/lpamchcfatttcyclehgsdphdhgehfghkkkdl..."
+
+    // check if it is valid ur string
+    if (!UR.validate(lowercase)) {
+      throw new Error("Invalid UR string");
+    }
+
+    const components = lowercase.slice(3).split("/");
+    let isFragment = false;
+    let seqNum = 0;
+    let seqLength = 0;
+    let payload = "";
+
+    // Check for the number of components
+    switch (components.length) {
+      case 2:
+        // single part ur
+        isFragment = false;
+        break;
+      case 3:
+        // multi part ur
+        isFragment = true;
+        break;
+      default:
+        throw new InvalidPathLengthError();
+    }
+
+    const type = components[0]; //e.g. "bytes"
+    if (isFragment) {
+      const seq = components[1]; //e.g. "6-23"
+      const [num, length] = seq.split("-").map(Number);
+      seqNum = num;
+      seqLength = length;
+      payload = components[2];
+    } else {
+      payload = components[1];
+    }
+
+    return {
+      type,
+      payload,
+      seqNum,
+      seqLength,
+      isFragment,
+    };
+  }
+}
+
+/// Helper functions
+
+/**
+ * Generates a uri. e.g. 'ur:bytes/6-22/lpamcmcfatrdcyzcpldpgwhdhtiaiaecgyktgsflguhshthfghjtjngrhsfegtiafegaktgugui'
+ * @param scheme scheme of the uri. e.g. "ur"
+ * @param pathComponents adds additional information to the uri in the form of a path (divided by "/"). e.g. "bytes/6-22/lpamcmcfatrdcyzcpldpgwhdhtiaiaecgyktgsflguhshthfghjtjngrhsfegtiafegaktgugui"
+ * @returns the complete uri.
+ */
+function joinUri(scheme: string, pathComponents: string[]): string {
+  const path = pathComponents.join("/");
+  return [scheme, path].join(":");
+}
+
+
+
+/**
+ * [seqNum, fragments.length, totalPayloadLength, checksum, fragment]
+ * 
+ * part = [
+ *	uint32 seqNum,
+ *	uint seqLen,
+ *	uint messageLen,
+ *	uint32 checksum,
+ *	bytes data
+ *  ] 
+ */
+export type IMultipartUrPayload = [number, number, number, number, Uint8Array];

package/src/classes/UrFountainDecoder.ts

@@ -0,0 +1,142 @@
+import { RegistryItem } from "../classes/RegistryItem.js";
+import { EncodingMethodName } from "../enums/EncodingMethodName.js";
+import { FountainDecoder, MultipartPayload, validateDecodedMultipart } from "./FountainDecoder.js";
+import { UR } from "./UR.js";
+
+export class UrFountainDecoder extends FountainDecoder {
+  public expectedType: string;
+  public resultUr: UR;
+  public decodedData: RegistryItem | any;
+
+  constructor(parts: UR[] | string[] = []) {
+    super();
+    parts.forEach((part) => {
+      this.receivePartUr(part);
+    });
+  }
+
+  public reset(): void {
+    super.reset();
+    this.resultUr = undefined;
+    this.expectedType = undefined;
+  }
+
+  setExpectedValuesUr(part: UR, decodedPart: MultipartPayload): void {
+    this.expectedType = part.type;
+    this.expectedPartCount = part.seqLength;
+    super.setExpectedValues(decodedPart);
+  }
+
+  protected validateUr(part: UR, decodedPart: MultipartPayload): boolean {
+    // Check if UR is a fragment
+    if (!part.isFragment) {
+      return false;
+    }
+
+    // Check the type of the UR
+    if (part.type !== this.expectedType) {
+      return false;
+    }
+
+    // Expect metadata ur seqNum to be equal to the decoded part seqNum
+    if (part.seqNum !== decodedPart.seqNum) {
+      return false;
+    }
+
+    // Expect metadata ur seqLength to be equal to the decoded part seqLength
+    if (part.seqLength !== decodedPart.seqLength) {
+      return false;
+    }
+
+    // Validate decoded paylad
+    return super.validatePart(decodedPart);
+  }
+
+  receivePartUr(part: UR | string): boolean {
+    // If we already have a result, we're done
+    if (this.done) {
+      return false;
+    }
+
+    // Convert string into UR
+    if (typeof part === "string") {
+      part = UR.fromString(part);
+    }
+
+    // If what we received is not a multupart UR, then we're done
+    if (!part.isFragment) {
+      // If this is not a fragment and we have not received any fragments yet then its the whole UR
+      if (!this.started) {
+        this.resultUr = part;
+        this.started = true;
+        this.done = true;
+
+        try {
+          this.decodedData = this.resultUr.decode();
+        } catch (error) {
+          this.error = error;
+        }
+
+        // Finish here
+        return true;
+      }
+      // If we have received fragments before then this is an error
+      else {
+        return false;
+      }
+    }
+
+    let parsed: MultipartPayload;
+    try {
+      const decoded = part.decode();
+      parsed = validateDecodedMultipart(decoded);
+    } catch (e) {
+      console.error(e);
+      return false;
+    }
+
+    // If this is the first part we've seen then set expected values
+    if (!this.started) this.setExpectedValuesUr(part, parsed);
+
+    // If this is a fragment validate UR
+    if (!this.validateUr(part, parsed)) {
+      return false;
+    }
+
+    return super.receivePart(parsed);
+  }
+
+  // Assemble data and generate single result UR
+  public finalize(): void {
+    super.finalize();
+
+    if (this.error) {
+      return;
+    }
+
+    if (this.resultRaw !== undefined) {
+      // Result data is already in CBOR
+      // Just convert it to bytewords instead of encoding it again
+      const payload = UR.pipeline.encode(this.resultRaw, { from: EncodingMethodName.hex });
+      this.resultUr = new UR({
+        type: this.expectedType,
+        payload: payload,
+      });
+
+      // Now Try to decode the result UR
+      try {
+        this.decodedData = this.resultUr.decode();
+      } catch (error) {
+        this.error = error;
+      }
+    }
+  }
+
+  getDecodedData(): RegistryItem | any {
+    if (!this.isSuccessful()) {
+      console.log("Fountain decoding was not successful");
+      return undefined;
+    }
+    return this.decodedData;
+  }
+}

package/src/classes/UrFountainEncoder.ts

@@ -0,0 +1,103 @@
+import { isRegistryItem, RegistryItem, RegistryItemBase } from "../classes/RegistryItem.js";
+import { UR } from "./UR.js";
+import { FountainEncoder } from "./FountainEncoder.js";
+import { EncodingMethodName } from "../enums/EncodingMethodName.js";
+
+/**
+ * UrFountainEncoder encodes data on the fly using an internal state to keep generating UR fragments of the payload.
+ * It extends the FountainEncoder class to provide additional functionality specific to UR encoding.
+ */
+export class UrFountainEncoder extends FountainEncoder {
+  /** The UR type of the input data */
+  private _type: string;
+  /** The original input data as a UR object */
+  private _inputUr: UR;
+  /** Reset counter to 1 after hitting `fragmentCount * ratio`; if undefined or 0, it goes forever */
+  public repeatAfterRatio = 2;
+
+  /**
+   * Creates an instance of UrFountainEncoder.
+   * @param input - The input data to be encoded, either as a RegistryItem or UR.
+   * @param maxFragmentLength - The maximum length of each fragment.
+   * @param minFragmentLength - The minimum length of each fragment.
+   * @param firstSeqNum - The sequence number to start with.
+   * @param repeatAfterRatio - The ratio after which the sequence number resets. Default is 2. If 0 fountain goes forever.
+   */
+  constructor(
+    input: RegistryItem | UR,
+    maxFragmentLength: number = 100,
+    minFragmentLength: number = 10,
+    firstSeqNum: number = 0,
+    repeatAfterRatio = 2
+  ) {
+
+    let inputUr;
+    // If the input is a RegistryItem, convert it to a Ur
+    if (input instanceof RegistryItemBase || isRegistryItem(input)) {
+      inputUr = UR.fromRegistryItem(input);
+    }
+    else {
+      inputUr = input;
+    }
+    
+    // Input in CBOR
+    let inputCBOR = inputUr.getPayloadCbor();
+
+    super(inputCBOR, maxFragmentLength, minFragmentLength, firstSeqNum);
+
+    this._inputUr = inputUr;
+    this._type = inputUr.type;
+    this.repeatAfterRatio = repeatAfterRatio;
+  }
+
+
+  /**
+   * 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 An array of UR objects representing the fragments.
+   */
+  getAllPartsUr(fountainRatio: number = 0): UR[] {
+    const allParts = super.getAllParts(fountainRatio);
+    return allParts.map((part, index) => this.fragment2Ur(index+1, part));
+  }
+
+  /**
+   * Give the 'next' fragment for the ur for which the fountainEncoder was created.
+   * @returns The 'next' fragment, represented as a Ur multipart string.
+   */
+  public nextPartUr(): UR {
+    // Reset the sequence number if we hit the ratio
+    if (this.repeatAfterRatio) {
+      if (this._seqNum > this._pureFragments.length * this.repeatAfterRatio) {
+        this._seqNum = 0;
+      }
+    }
+    const encodedFragment = super.nextPart();
+    return this.fragment2Ur(this._seqNum, encodedFragment);
+  }
+
+  /**
+   * Converts a fragment to a UR object.
+   * @param seqNum - The sequence number of the fragment.
+   * @param fragment - The fragment data as a Uint8Array.
+   * @returns A UR object representing the fragment.
+   */
+  private fragment2Ur(seqNum:number, fragment:Uint8Array) {
+    // Fragment is already encoded in CBOR
+    // Just convert it to bytewords instead of encoding it again
+    const payload = UR.pipeline.encode(fragment, {from: EncodingMethodName.hex});
+    if (this.isSinglePart()) {
+      return new UR({
+        type: this._type,
+        payload: payload,
+      });
+    }
+    return new UR({
+      type: this._type,
+      payload: payload,
+      seqNum: seqNum,
+      seqLength: this._pureFragments.length,
+      isFragment: true,
+    })    
+  }  
+}

package/src/classes/key.helper.ts

@@ -0,0 +1,85 @@
+/**
+ * This file contains helper functions for encoding and decoding keys
+ */
+
+/**
+ * Interface for the key to integer mapping
+ */
+export type IKeyMap = Record<string, string | number>;
+
+/**
+ * For some CDDL types we use integer as keys to keep the CBOR encoded data small
+ * This function converts the data keys to their respective integer values
+ *
+ * It needs to return MAP because cbor library only then encodes the keys as integers
+ *
+ * @param data Object that has key value pairs
+ * @param keyMap  Map of the keys to integers values
+ * @returns Map with integer keys
+ */
+export function encodeKeys(
+  data: object,
+  keyMap: IKeyMap,
+  allowKeysNotInMap: boolean
+): Map<string | number, any> {
+  const map = new Map();
+  // If we have a mapping, use it to map the data
+  // Check if our data is an object
+  if (typeof data !== "object") return undefined;
+
+  // Create a set from the keys of the data
+  const keys = new Set(Object.keys(data));
+
+  // Add the keys in the correct order to the map
+  for (const key in keyMap) {
+    // Check if the key exists in the data
+    if(data[key] !== undefined) map.set(keyMap[key], data[key]);
+    keys.delete(key);
+  }
+
+  if (allowKeysNotInMap) {
+    // Add other keys as string if they are not existent in the map
+    keys.forEach((key) => {
+      map.set(key, data[key]);
+    });
+  }
+
+  return map;
+}
+
+/**
+ * For some CDDL types we use integer as keys to keep the CBOR encoded data small
+ * This function converts the data keys back to their respective string values
+ *
+ * @param _data Object that has encoded key - value pairs
+ * @param keyMap Map of the keys to integer values
+ * @returns Object with string keys
+ */
+export function decodeKeys(
+  data: Map<string | number, any> | Record<string | number, any>,
+  keyMap: IKeyMap,
+  allowKeysNotInMap: boolean
+): object {
+  // If we have a mapping, use it to map the data
+  const result = {};
+  // Convert the data to a map if it is not already
+  const _data = data instanceof Map ? data : new Map(Object.entries(data));
+
+  // Get all the keys in the data
+  const keys = new Set(_data.keys());
+
+  // Add the keys in the correct order
+  for (const key in keyMap) {
+    if (_data.has(keyMap[key])) result[key] = _data.get(keyMap[key]);
+    keys.delete(keyMap[key]);
+  }
+
+  if (allowKeysNotInMap) {
+    // Add other keys as string if they are not existent in the map
+    keys.forEach((key) => {
+      result[key] = _data.get(key);
+    });
+  }
+
+  return result;
+}

package/src/encodingMethods/BytewordEncoding.ts

@@ -0,0 +1,23 @@
+import { STYLES, decode, encode } from "./bytewords.js";
+import { EncodingMethodName } from "../enums/EncodingMethodName.js";
+import { IEncodingMethod } from "../interfaces/IEncodingMethod.js";
+
+export class BytewordEncoding implements IEncodingMethod<string, string> {
+  private _name: EncodingMethodName = EncodingMethodName.bytewords;
+
+  readonly _style: STYLES;
+
+  get name(): EncodingMethodName {
+      return this._name;
+  }
+  
+  constructor(style: STYLES = STYLES.MINIMAL) {
+    this._style = style;
+  }
+  encode(payload: string): string {
+    return encode(payload, this._style);
+  }
+  decode(payload: string): string {
+    return decode(payload, this._style);
+  }
+}