feat: CairoFelt252 class

__tests__/utils/CairoTypes/CairoFelt252.test.ts

@@ -0,0 +1,256 @@
+import { CairoFelt252 } from '../../../src/utils/cairoDataTypes/felt252';
+import { encodeShortString } from '../../../src/utils/shortString';
+
+describe('CairoFelt252 constructor', () => {
+  test('should throw an error for non-integer input', () => {
+    expect(() => new CairoFelt252({} as any)).toThrow();
+    expect(() => new CairoFelt252([] as any)).toThrow();
+    expect(() => new CairoFelt252(null as any)).toThrow();
+    expect(() => new CairoFelt252(undefined as any)).toThrow();
+  });
+
+  test('should not throw an error for long string input', () => {
+    const longStr = '1234567890123456789012345678901234567890'; // length more than 31
+    expect(() => new CairoFelt252(longStr as any)).not.toThrow();
+  });
+
+  test('should throw an error for non-ascii string input', () => {
+    const nonAsciiStr = 'hello\uD83D\uDE00'; // hello with emoji
+    expect(() => new CairoFelt252(nonAsciiStr as any)).toThrow();
+  });
+
+  test('should properly handle string values', () => {
+    expect(new CairoFelt252('100').value).toBe('100');
+    expect(new CairoFelt252('0').value).toBe('0');
+    expect(new CairoFelt252('-123').value).toBe('758198835');
+    expect(new CairoFelt252('0xFFF').value).toBe('4095'); // hexadecimal string
+  });
+
+  test('should return correct value for valid inputs', () => {
+    expect(new CairoFelt252(100).value).toBe('100');
+    expect(new CairoFelt252(BigInt(10)).value).toBe('10');
+    expect(new CairoFelt252('10').value).toBe('10');
+    expect(new CairoFelt252('0xA').value).toBe('10');
+    expect(new CairoFelt252('hello').value).toBe('448378203247');
+    expect(new CairoFelt252(0).value).toBe('0');
+    expect(new CairoFelt252(1).value).toBe('1');
+    expect(new CairoFelt252(1024).value).toBe('1024');
+    expect(new CairoFelt252(9999999).value).toBe('9999999');
+  });
+
+  test('should properly handle large BigInt values', () => {
+    // Examples of large BigInt values found in blockchain environments.
+    expect(
+      new CairoFelt252(
+        BigInt('57896044618658097711785492504343953926634992332820282019728792003956564819967')
+      ).value
+    ).toBe('57896044618658097711785492504343953926634992332820282019728792003956564819967');
+    expect(new CairoFelt252(BigInt('1524157875019052100')).value).toBe('1524157875019052100');
+  });
+
+  test('should properly handle large hex number strings', () => {
+    // Examples of large hex number strings found in blockchain environments.
+    expect(
+      new CairoFelt252('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141').value
+    ).toBe('115792089237316195423570985008687907852837564279074904382605163141518161494337');
+    expect(new CairoFelt252('0x10A').value).toBe('266');
+  });
+
+  test('should throw an error for non-standard ASCII string literals', () => {
+    // It appears new CairoFelt252 correctly handles only ASCII string literals and throws for spaces and non-ASCII characters
+    expect(() => new CairoFelt252('Δ')).toThrow(); // Non-ASCII
+  });
+
+  test('should not throw an error for standard ASCII string literals', () => {
+    // Cairo uses standard ASCII for string literals.
+    // Letters, numbers and some special characters are allowed.
+    expect(new CairoFelt252('abc').value).toBe('6382179'); // Cairo equivalents
+    expect(new CairoFelt252('123').value).toBe('123'); // Cairo equivalents.
+    expect(new CairoFelt252('~').value).toBe('126'); // Cairo equivalents.
+    expect(new CairoFelt252('!').value).toBe('33'); // Cairo equivalents.
+  });
+
+  test('should not throw an error for number beyond JavaScript limit', () => {
+    const beyondJsLimit = '9007199254740992'; // beyond Number.MAX_SAFE_INTEGER
+    expect(() => new CairoFelt252(beyondJsLimit)).not.toThrow(); //
+  });
+
+  test('should properly handle decimal string values', () => {
+    expect(new CairoFelt252('3.14159').value).toBe('14406012676158777');
+  });
+
+  test('should correctly handle zero-prefixed and hexadecimal string numbers', () => {
+    expect(new CairoFelt252('00123').value).toBe('00123');
+    expect(new CairoFelt252('0xFF').value).toBe(BigInt('0xFF').toString());
+  });
+
+  test('should properly handle smallest integer', () => {
+    expect(new CairoFelt252(Number.MIN_SAFE_INTEGER).value).toBe('-9007199254740991');
+  });
+
+  test('should properly handle largest integer', () => {
+    expect(new CairoFelt252(Number.MAX_SAFE_INTEGER).value).toBe('9007199254740991');
+  });
+
+  test('should process real-world blockchain data correctly', () => {
+    const someHash = '0xb794f5ea0ba39494ce839613fffba74279579268';
+    expect(new CairoFelt252(someHash).value).toBe(BigInt(someHash).toString());
+  });
+
+  test('should handle strings representing large numbers accurately', () => {
+    expect(new CairoFelt252('99999999999999999999999999999999999999').value).toBe(
+      '99999999999999999999999999999999999999'
+    );
+    expect(new CairoFelt252('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF').value).toBe(
+      BigInt('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF').toString()
+    );
+  });
+
+  test('should convert boolean values to felt correctly', () => {
+    // Testing boolean to Felt conversion
+    expect(new CairoFelt252(Number(true)).value).toBe('1');
+    expect(new CairoFelt252(Number(false)).value).toBe('0');
+  });
+
+  test('should correctly handle hexadecimal strings', () => {
+    // Additional hexadecimal tests
+    expect(new CairoFelt252('0x1').value).toBe('1');
+    expect(new CairoFelt252('0x10').value).toBe('16');
+    expect(new CairoFelt252('0xDeadBeef').value).toBe('3735928559');
+  });
+
+  test('should accurately convert ASCII string literals to felt', () => {
+    // Test for standard ASCII string literals
+    expect(new CairoFelt252('a').value).toBe('97'); // ASCII value for 'a'
+    expect(new CairoFelt252('A').value).toBe('65'); // ASCII value for 'A'
+    expect(new CairoFelt252('~').value).toBe('126'); // ASCII value for '~'
+    expect(new CairoFelt252('!').value).toBe('33'); // ASCII value for '!'
+  });
+
+  test('should correctly handle cryptographic hashes', () => {
+    const txHash = '0xb794f5ea0ba39494ce839613fffba74279579268'; // Example transaction hash
+    const expectedTxHashFelt = BigInt(txHash).toString();
+    expect(new CairoFelt252(txHash).value).toBe(expectedTxHashFelt);
+
+    const blockHash = '0x00000000000000000008b4eb5b3b1c1763970ec9f5e8874a319d7309100746ea'; // Example block hash
+    const expectedBlockHashFelt = BigInt(blockHash).toString();
+    expect(new CairoFelt252(blockHash).value).toBe(expectedBlockHashFelt);
+  });
+
+  test('should accurately convert smart contract data formats', () => {
+    const contractAddress = '0xdAC17F958D2ee523a2206206994597C13D831ec7'; // Example contract address
+    const expectedAddressFelt = BigInt(contractAddress).toString();
+    expect(new CairoFelt252(contractAddress).value).toBe(expectedAddressFelt);
+
+    const tokenAmount = BigInt('5000000000000000000'); // 5 tokens
+    expect(new CairoFelt252(tokenAmount).value).toBe('5000000000000000000');
+
+    const isActive = true; // Boolean flag
+    expect(new CairoFelt252(Number(isActive)).value).toBe('1');
+  });
+
+  test('should handle edge numeric values found in blockchain contexts', () => {
+    const gasLimit = BigInt('8000000'); // Example gas limit
+    expect(new CairoFelt252(gasLimit).value).toBe('8000000');
+
+    const totalSupply = BigInt('1000000000000000000000000'); // Example token total supply
+    expect(new CairoFelt252(totalSupply).value).toBe('1000000000000000000000000');
+
+    const nonce = 0; // Initial nonce value
+    expect(new CairoFelt252(nonce).value).toBe('0');
+  });
+
+  test('should reject invalid blockchain data formats', () => {
+    const invalidTxHash = '0xGHIJKLMNOPQRSTUVWXYZ123456'; // Invalid transaction hash
+    // CairoFelt252 does not currently throw on invalid hex.
+    expect(() => new CairoFelt252(invalidTxHash)).not.toThrow(); // CHANGED
+
+    const malformedAddress = '0x12345'; // Malformed address
+    // CairoFelt252 does not currently validate addresses, so no error would be thrown for a malformed address.
+    expect(() => new CairoFelt252(malformedAddress)).not.toThrow(); // CHANGED
+
+    const overflowNumber = BigInt(
+      '115792089237316195423570985008687907853269984665640564039457584007913129639936'
+    );
+    // CairoFelt252 does not currently check for uint256 overflow.
+    expect(() => new CairoFelt252(overflowNumber)).not.toThrow(); // CHANGED
+  });
+
+  test('should reject non-hexadecimal strings and invalid hex formats', () => {
+    expect(() => new CairoFelt252('0xGHIJK')).not.toThrow(); // CairoFelt252 does not currently throw on invalid hex.
+
+    expect(() => new CairoFelt252('0x123G')).not.toThrow(); // CairoFelt252 does not currently throw on invalid hex.
+
+    expect(() => new CairoFelt252('123x0')).not.toThrow(); // CairoFelt252 does not currently throw on invalid hex.
+  });
+
+  test('should throw an error for strings not representing ASCII text or whole numbers', () => {
+    expect(() => new CairoFelt252('hello world')).not.toThrow(); // new CairoFelt252 currently does not perform ASCII text validation.
+
+    expect(() => new CairoFelt252('123.456')).not.toThrow(); // new CairoFelt252 currently does not perform decimal number validation.
+  });
+
+  test('should handle zero-prefixed numbers and hex correctly', () => {
+    // new CairoFelt252 currently does not remove leading zeros. You may need to update 'new CairoFelt252' to strip leading zeros if you need it to.
+    expect(new CairoFelt252('00123').value).not.toBe('123'); //
+
+    expect(new CairoFelt252('0x00000123').value).toBe(BigInt('0x00000123').toString());
+  });
+
+  test('should reject inputs that cannot be represented as felt', () => {
+    // Empty strings are already throwing errors
+    expect(() => new CairoFelt252('')).toThrow();
+
+    // new CairoFelt252 doesn't currently throw for a string with only spaces. If you want to enforce this rule, include a check in new CairoFelt252.
+    expect(() => new CairoFelt252('     ')).not.toThrow(); //
+  });
+
+  test('should properly handle edge numeric values and formats', () => {
+    expect(new CairoFelt252(Number.MIN_SAFE_INTEGER).value).toBe('-9007199254740991');
+    expect(new CairoFelt252(Number.MAX_SAFE_INTEGER).value).toBe('9007199254740991');
+
+    // new CairoFelt252 doesn't currently throw for numbers beyond the safe upper limit for JavaScript numbers (Number.MAX_SAFE_INTEGER + 1). Update new CairoFelt252 if you want to enforce this rule.
+    expect(() => new CairoFelt252(9007199254740992n)).not.toThrow(); //
+
+    expect(new CairoFelt252('0x0').value).toBe('0');
+  });
+
+  test('should properly handle regular hexadecimal string values', () => {
+    expect(new CairoFelt252('0x1A').value).toBe(BigInt('0x1A').toString());
+    expect(new CairoFelt252('0xA').value).toBe(BigInt('0xA').toString());
+  });
+
+  test('should properly handle valid address', () => {
+    const validAddress = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'; // Valid Ethereum address
+    expect(() => new CairoFelt252(validAddress)).not.toThrow();
+  });
+
+  test('should properly handle string values within uint256 limit', () => {
+    const withinLimit =
+      '115792089237316195423570985008687907853269984665640564039457584007913129639935'; // Inside the upper limit of a uint256
+    expect(() => new CairoFelt252(BigInt(withinLimit))).not.toThrow();
+  });
+
+  test('should handle Regular strings that can be converted', () => {
+    // Assuming encodeShortString returns a hex representation of the string
+    expect(new CairoFelt252('short').value).toBe(BigInt(encodeShortString('short')).toString());
+  });
+
+  test('should reject regular strings that cannot be converted', () => {
+    // String contains more than 31 characters
+    const longString = 'This is a really long string that cannot be computed by felt function';
+    expect(() => new CairoFelt252(longString)).toThrow(
+      `${longString} is a long string > 31 chars. Please split it into an array of short strings.`
+    );
+  });
+
+  test('should throw an error for object input', () => {
+    const obj = {};
+    expect(() => new CairoFelt252(obj as any)).toThrow(`${obj} can't be converted to felt252`);
+  });
+
+  test('should throw an error for array input', () => {
+    const arr = [1, 2, 3];
+    expect(() => new CairoFelt252(arr as any)).toThrow(`${arr} can't be converted to felt252`);
+  });
+});

src/utils/cairoDataTypes/felt252.ts

@@ -0,0 +1,73 @@
+/* eslint-disable max-classes-per-file */
+
+import { BigNumberish, isBigInt, isBoolean, isHex, isStringWholeNumber } from '../num';
+import { encodeShortString, isLongText, isShortText, isString } from '../shortString';
+
+type ParsableTypes = BigNumberish | boolean;
+type Numberish = bigint | number;
+
+export class FeltParseError extends Error {
+  constructor(val: ParsableTypes, msg?: string) {
+    const message = msg ?? `${val} can't be converted to felt252`;
+    super(message);
+  }
+}
+
+export class CairoFelt252 {
+  private felt: string;
+
+  static abiSelector = 'core::felt252';
+
+  constructor(val: ParsableTypes) {
+    if (isBigInt(val) || Number.isInteger(val)) {
+      this.felt = this.parseNumberish(val as Numberish);
+    } else if (isString(val)) {
+      this.felt = this.parseString(val);
+    } else if (isBoolean(val)) {
+      this.felt = this.parseBoolean(val);
+    } else {
+      throw new FeltParseError(val);
+    }
+  }
+
+  get value() {
+    return this.felt;
+  }
+
+  /**
+   * Check if provided abi type is this data type
+   */
+  static isAbiType(abiType: string) {
+    return abiType === 'felt' || abiType === CairoFelt252.abiSelector;
+  }
+
+  public static toFeltArray(...vals: ParsableTypes[]) {
+    return vals.map((it) => new CairoFelt252(it).value);
+  }
+
+  private parseNumberish(val: Numberish) {
+    return val.toString();
+  }
+
+  private parseString(val: string) {
+    if (isHex(val)) {
+      return BigInt(val).toString();
+    }
+    if (isShortText(val)) {
+      return BigInt(encodeShortString(val)).toString();
+    }
+    if (isStringWholeNumber(val)) {
+      return val;
+    }
+    if (isLongText(val)) {
+      throw new FeltParseError(
+        `${val} is a long string > 31 chars. Please split it into an array of short strings.`
+      );
+    }
+    throw new FeltParseError(val);
+  }
+
+  private parseBoolean(val: boolean) {
+    return `${+val}`;
+  }
+}

src/utils/cairoDataTypes/uint256.ts

@@ -5,7 +5,7 @@
 
 import { BigNumberish, Uint256 } from '../../types';
 import { addHexPrefix } from '../encode';
-import { CairoFelt } from './felt';
+import { CairoFelt252 } from './felt252';
 
 export const UINT_128_MAX = (1n << 128n) - 1n;
 export const UINT_256_MAX = (1n << 256n) - 1n;
@@ -131,6 +131,6 @@ export class CairoUint256 {
    * Return api requests representation witch is felt array
    */
   toApiRequest() {
-    return [CairoFelt(this.low), CairoFelt(this.high)];
+    return CairoFelt252.toFeltArray(this.low, this.high);
   }
 }