From 97a08c5949a0f96fd218ded30e1ce36fae07f319 Mon Sep 17 00:00:00 2001 From: Toni Tabak Date: Fri, 8 Sep 2023 17:12:55 +0200 Subject: [PATCH] fix: interface fix and docs update --- src/utils/calldata/cairo.ts | 36 +++++++++++---- src/utils/encode.ts | 92 ++++++++++++++++++++++++++++++++++--- 2 files changed, 112 insertions(+), 16 deletions(-) diff --git a/src/utils/calldata/cairo.ts b/src/utils/calldata/cairo.ts index 25d09d965..88f127759 100644 --- a/src/utils/calldata/cairo.ts +++ b/src/utils/calldata/cairo.ts @@ -3,6 +3,7 @@ import { isBigInt, isHex, isStringWholeNumber } from '../num'; import { encodeShortString, isShortString, isText } from '../shortString'; import { UINT_128_MAX, isUint256 } from '../uint256'; +// Intended for internal usage, maybe should be exported somewhere else and not exported to utils export const isLen = (name: string) => /_len$/.test(name); export const isTypeFelt = (type: string) => type === 'felt' || type === 'core::felt252'; export const isTypeArray = (type: string) => @@ -24,7 +25,6 @@ export const isTypeContractAddress = (type: string) => export const isTypeEthAddress = (type: string) => type === 'core::starknet::eth_address::EthAddress'; export const isCairo1Type = (type: string) => type.includes('core::'); - export const getArrayType = (type: string) => { if (isCairo1Type(type)) { return type.substring(type.indexOf('<') + 1, type.lastIndexOf('>')); @@ -33,10 +33,9 @@ export const getArrayType = (type: string) => { }; /** - * tells if an ABI comes from a Cairo 1 contract - * - * @param abi representing the interface of a Cairo contract - * @returns TRUE if it is an ABI from a Cairo1 contract + * Test if an ABI comes from a Cairo 1 contract + * @param abi Abi - representing the interface of a Cairo contract + * @returns boolean - TRUE if it is an ABI from a Cairo1 contract * @example * ```typescript * const isCairo1: boolean = isCairo1Abi(myAbi: Abi); @@ -61,13 +60,19 @@ export function isCairo1Abi(abi: Abi): boolean { } /** - * named tuple are described as js object {} - * struct types are described as js object {} - * array types are described as js array [] + * named tuple cairo type are described as js object {} + * struct cairo type are described as js object {} + * array cairo type are described as js array [] */ /** - * Uint256 cairo type (helper for common struct type) + * Create Uint256 Cairo type (helper for common struct type) + * @param it BigNumberish + * @returns Uint256 + * @example + * ```typescript + * uint256('892349863487563453485768723498'); + * ``` */ export const uint256 = (it: BigNumberish): Uint256 => { const bn = BigInt(it); @@ -83,12 +88,23 @@ export const uint256 = (it: BigNumberish): Uint256 => { /** * unnamed tuple cairo type (helper same as common struct type) */ +/** + * Create unnamed tuple Cairo type (helper same as common struct type) + * @param args BigNumberish[] | object[] | boolean[] + * @returns Record + * @example + * ```typescript + * tuple(1,'0x101',16); + * ``` + */ export const tuple = ( ...args: (BigNumberish | object | boolean)[] ): Record => ({ ...args }); /** - * felt cairo type + * Create felt Cairo type (cairo type helper) + * @param it BigNumberish + * @returns felt-string */ export function felt(it: BigNumberish): string { // BN or number diff --git a/src/utils/encode.ts b/src/utils/encode.ts index 5d891d614..56e92024b 100644 --- a/src/utils/encode.ts +++ b/src/utils/encode.ts @@ -3,39 +3,85 @@ export const IS_BROWSER = typeof window !== 'undefined'; const STRING_ZERO = '0'; +/** + * Some function imported from https://github.com/pedrouid/enc-utils/blob/master/src/index.ts + * enc-utils is no dependency to avoid using `Buffer` which just works in node and no browsers + */ + +/** + * Convert array buffer to string + * internal usage + * @param array ArrayBuffer + * @returns string + */ export function arrayBufferToString(array: ArrayBuffer): string { return new Uint8Array(array).reduce((data, byte) => data + String.fromCharCode(byte), ''); } +/** + * Convert string to array buffer + * internal usage + * @param s string + * @returns Uint8Array + */ export function stringToArrayBuffer(s: string): Uint8Array { return Uint8Array.from(s, (c) => c.charCodeAt(0)); } +/** + * Convert string to array buffer (browser and node compatible) + * @param a string + * @returns Uint8Array + */ export function atobUniversal(a: string): Uint8Array { return IS_BROWSER ? stringToArrayBuffer(atob(a)) : Buffer.from(a, 'base64'); } +/** + * Convert array buffer to string (browser and node compatible) + * @param b ArrayBuffer + * @returns string + */ export function btoaUniversal(b: ArrayBuffer): string { return IS_BROWSER ? btoa(arrayBufferToString(b)) : Buffer.from(b).toString('base64'); } +/** + * Convert array buffer to hex-string + * @param buffer Uint8Array + * @returns hex-string + */ export function buf2hex(buffer: Uint8Array) { return [...buffer].map((x) => x.toString(16).padStart(2, '0')).join(''); } /** - * Some function imported from https://github.com/pedrouid/enc-utils/blob/master/src/index.ts - * enc-utils is no dependency to avoid using `Buffer` which just works in node and no browsers + * Remove hex prefix '0x' from hex-string + * @param hex hex-string + * @returns base16-string */ - export function removeHexPrefix(hex: string): string { return hex.replace(/^0x/i, ''); } +/** + * Add hex prefix '0x' to base16-string + * @param hex base16-string + * @returns hex-string + */ export function addHexPrefix(hex: string): string { return `0x${removeHexPrefix(hex)}`; } +/** + * Prepend or append to string + * internal usage + * @param str string + * @param length number + * @param left boolean + * @param padding STRING_ZERO + * @returns string + */ function padString(str: string, length: number, left: boolean, padding = STRING_ZERO): string { const diff = length - str.length; let result = str; @@ -46,19 +92,48 @@ function padString(str: string, length: number, left: boolean, padding = STRING_ return result; } +/** + * Prepend string (default with '0') + * @param str string + * @param length number + * @param padding STRING_ZERO + * @returns string + */ export function padLeft(str: string, length: number, padding = STRING_ZERO): string { return padString(str, length, true, padding); } -export function calcByteLength(length: number, byteSize = 8): number { +/** + * Calculate byte length of string + * no-internal usage + * @param str string + * @param byteSize =8 + * @returns number + */ +export function calcByteLength(str: string, byteSize = 8): number { + const { length } = str; const remainder = length % byteSize; return remainder ? ((length - remainder) / byteSize) * byteSize + byteSize : length; } +/** + * Prepend '0' to string bytes + * no-internal usage + * @param str string + * @param byteSize =8 + * @param padding STRING_ZERO + * @returns string + */ export function sanitizeBytes(str: string, byteSize = 8, padding = STRING_ZERO): string { - return padLeft(str, calcByteLength(str.length, byteSize), padding); + return padLeft(str, calcByteLength(str, byteSize), padding); } +/** + * Prepend '0' to hex-string bytes + * no-internal usage + * @param hex hex-string + * @returns hex-string + */ export function sanitizeHex(hex: string): string { hex = removeHexPrefix(hex); hex = sanitizeBytes(hex, 2); @@ -68,7 +143,12 @@ export function sanitizeHex(hex: string): string { return hex; } -// implemented using TextEncoder to make it isomorphic +/** + * Convert utf8-string to Uint8Array + * implemented using TextEncoder to make it isomorphic + * @param str utf8-string + * @returns Uint8Array + */ export function utf8ToArray(str: string): Uint8Array { return new TextEncoder().encode(str); }