From 13d64dcce71484bf32166e53cae862b5d90ba60b Mon Sep 17 00:00:00 2001 From: Bo Yao Date: Fri, 18 Nov 2022 15:31:39 +0800 Subject: [PATCH] add remaining doc strings --- lib/api.d.ts | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++ lib/api.js | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++ src/api.ts | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 273 insertions(+) diff --git a/lib/api.d.ts b/lib/api.d.ts index f8eff3c68..04d6ae2bf 100644 --- a/lib/api.d.ts +++ b/lib/api.d.ts @@ -251,16 +251,107 @@ export declare function promiseResult(promiseIndex: PromiseIndex): Bytes; * @param promiseIndex - The index of the promise to execute. */ export declare function promiseReturn(promiseIndex: PromiseIndex): void; +/** + * Returns sha256 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export declare function sha256(value: Bytes): Bytes; +/** + * Returns keccak256 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export declare function keccak256(value: Bytes): Bytes; +/** + * Returns keccak512 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export declare function keccak512(value: Bytes): Bytes; +/** + * Returns ripemd160 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export declare function ripemd160(value: Bytes): Bytes; +/** + * Recovers an ECDSA signer address from a 32-byte message hash and a corresponding + * signature along with v recovery byte. Takes in an additional flag to check for + * malleability of the signature which is generally only ideal for transactions. + * + * @param hash - 32-byte message hash + * @param sig - signature + * @param v - number of recovery byte + * @param malleabilityFlag - whether to check malleability + * @returns 64 bytes representing the public key if the recovery was successful. + */ export declare function ecrecover(hash: Bytes, sig: Bytes, v: number, malleabilityFlag: number): Bytes | null; +/** + * Panic the transaction execution with given message + * @param msg - panic message in raw bytes, which should be a valid UTF-8 sequence + */ export declare function panicUtf8(msg: Bytes): never; +/** + * Log the message in transaction logs + * @param msg - message in raw bytes, which should be a valid UTF-8 sequence + */ export declare function logUtf8(msg: Bytes): void; +/** + * Log the message in transaction logs + * @param msg - message in raw bytes, which should be a valid UTF-16 sequence + */ export declare function logUtf16(msg: Bytes): void; +/** + * Returns the number of staked NEAR of given validator, in yoctoNEAR + * @param accountId - validator's AccountID + * @returns - staked amount + */ export declare function validatorStake(accountId: Bytes): bigint; +/** + * Returns the number of staked NEAR of all validators, in yoctoNEAR + * @returns total staked amount + */ export declare function validatorTotalStake(): bigint; +/** + * Computes multiexp on alt_bn128 curve using Pippenger's algorithm \sum_i + * mul_i g_{1 i} should be equal result. + * + * @param value - equence of (g1:G1, fr:Fr), where + * G1 is point (x:Fq, y:Fq) on alt_bn128, + * alt_bn128 is Y^2 = X^3 + 3 curve over Fq. + * `value` is encoded as packed, little-endian + * `[((u256, u256), u256)]` slice. + * + * @returns multi exp sum + */ export declare function altBn128G1Multiexp(value: Bytes): Bytes; +/** + * Computes sum for signed g1 group elements on alt_bn128 curve \sum_i + * (-1)^{sign_i} g_{1 i} should be equal result. + * + * @param value - sequence of (sign:bool, g1:G1), where + * G1 is point (x:Fq, y:Fq) on alt_bn128, + * alt_bn128 is Y^2 = X^3 + 3 curve over Fq. + * value` is encoded a as packed, little-endian + * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice. + * + * @returns sum over Fq. + */ export declare function altBn128G1Sum(value: Bytes): Bytes; +/** + * Computes pairing check on alt_bn128 curve. + * \sum_i e(g_{1 i}, g_{2 i}) should be equal one (in additive notation), e(g1, g2) is Ate pairing + * + * @param value - sequence of (g1:G1, g2:G2), where + * G2 is Fr-ordered subgroup point (x:Fq2, y:Fq2) on alt_bn128 twist, + * alt_bn128 twist is Y^2 = X^3 + 3/(i+9) curve over Fq2 + * Fq2 is complex field element (re: Fq, im: Fq) + * G1 is point (x:Fq, y:Fq) on alt_bn128, + * alt_bn128 is Y^2 = X^3 + 3 curve over Fq + * `value` is encoded a as packed, little-endian + * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice. + * + * @returns whether pairing check pass + */ export declare function altBn128PairingCheck(value: Bytes): boolean; diff --git a/lib/api.js b/lib/api.js index ff051a553..0c5b38caa 100644 --- a/lib/api.js +++ b/lib/api.js @@ -362,22 +362,53 @@ export function promiseResult(promiseIndex) { export function promiseReturn(promiseIndex) { env.promise_return(promiseIndex); } +/** + * Returns sha256 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export function sha256(value) { env.sha256(value, 0); return env.read_register(0); } +/** + * Returns keccak256 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export function keccak256(value) { env.keccak256(value, 0); return env.read_register(0); } +/** + * Returns keccak512 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export function keccak512(value) { env.keccak512(value, 0); return env.read_register(0); } +/** + * Returns ripemd160 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export function ripemd160(value) { env.ripemd160(value, 0); return env.read_register(0); } +/** + * Recovers an ECDSA signer address from a 32-byte message hash and a corresponding + * signature along with v recovery byte. Takes in an additional flag to check for + * malleability of the signature which is generally only ideal for transactions. + * + * @param hash - 32-byte message hash + * @param sig - signature + * @param v - number of recovery byte + * @param malleabilityFlag - whether to check malleability + * @returns 64 bytes representing the public key if the recovery was successful. + */ export function ecrecover(hash, sig, v, malleabilityFlag) { const returnValue = env.ecrecover(hash, sig, v, malleabilityFlag, 0); if (returnValue === 0n) { @@ -386,29 +417,89 @@ export function ecrecover(hash, sig, v, malleabilityFlag) { return env.read_register(0); } // NOTE: "env.panic(msg)" is not exported, use "throw Error(msg)" instead +/** + * Panic the transaction execution with given message + * @param msg - panic message in raw bytes, which should be a valid UTF-8 sequence + */ export function panicUtf8(msg) { env.panic_utf8(msg); } +/** + * Log the message in transaction logs + * @param msg - message in raw bytes, which should be a valid UTF-8 sequence + */ export function logUtf8(msg) { env.log_utf8(msg); } +/** + * Log the message in transaction logs + * @param msg - message in raw bytes, which should be a valid UTF-16 sequence + */ export function logUtf16(msg) { env.log_utf16(msg); } +/** + * Returns the number of staked NEAR of given validator, in yoctoNEAR + * @param accountId - validator's AccountID + * @returns - staked amount + */ export function validatorStake(accountId) { return env.validator_stake(accountId); } +/** + * Returns the number of staked NEAR of all validators, in yoctoNEAR + * @returns total staked amount + */ export function validatorTotalStake() { return env.validator_total_stake(); } +/** + * Computes multiexp on alt_bn128 curve using Pippenger's algorithm \sum_i + * mul_i g_{1 i} should be equal result. + * + * @param value - equence of (g1:G1, fr:Fr), where + * G1 is point (x:Fq, y:Fq) on alt_bn128, + * alt_bn128 is Y^2 = X^3 + 3 curve over Fq. + * `value` is encoded as packed, little-endian + * `[((u256, u256), u256)]` slice. + * + * @returns multi exp sum + */ export function altBn128G1Multiexp(value) { env.alt_bn128_g1_multiexp(value, 0); return env.read_register(0); } +/** + * Computes sum for signed g1 group elements on alt_bn128 curve \sum_i + * (-1)^{sign_i} g_{1 i} should be equal result. + * + * @param value - sequence of (sign:bool, g1:G1), where + * G1 is point (x:Fq, y:Fq) on alt_bn128, + * alt_bn128 is Y^2 = X^3 + 3 curve over Fq. + * value` is encoded a as packed, little-endian + * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice. + * + * @returns sum over Fq. + */ export function altBn128G1Sum(value) { env.alt_bn128_g1_sum(value, 0); return env.read_register(0); } +/** + * Computes pairing check on alt_bn128 curve. + * \sum_i e(g_{1 i}, g_{2 i}) should be equal one (in additive notation), e(g1, g2) is Ate pairing + * + * @param value - sequence of (g1:G1, g2:G2), where + * G2 is Fr-ordered subgroup point (x:Fq2, y:Fq2) on alt_bn128 twist, + * alt_bn128 twist is Y^2 = X^3 + 3/(i+9) curve over Fq2 + * Fq2 is complex field element (re: Fq, im: Fq) + * G1 is point (x:Fq, y:Fq) on alt_bn128, + * alt_bn128 is Y^2 = X^3 + 3 curve over Fq + * `value` is encoded a as packed, little-endian + * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice. + * + * @returns whether pairing check pass + */ export function altBn128PairingCheck(value) { return env.alt_bn128_pairing_check(value) === 1n; } diff --git a/src/api.ts b/src/api.ts index 131b43a7e..1a20b4c83 100644 --- a/src/api.ts +++ b/src/api.ts @@ -661,26 +661,57 @@ export function promiseReturn(promiseIndex: PromiseIndex): void { env.promise_return(promiseIndex as unknown as bigint); } +/** + * Returns sha256 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export function sha256(value: Bytes): Bytes { env.sha256(value, 0); return env.read_register(0); } +/** + * Returns keccak256 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export function keccak256(value: Bytes): Bytes { env.keccak256(value, 0); return env.read_register(0); } +/** + * Returns keccak512 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export function keccak512(value: Bytes): Bytes { env.keccak512(value, 0); return env.read_register(0); } +/** + * Returns ripemd160 hash of given value + * @param value - value to be hashed, in Bytes + * @returns hash result in Bytes + */ export function ripemd160(value: Bytes): Bytes { env.ripemd160(value, 0); return env.read_register(0); } +/** + * Recovers an ECDSA signer address from a 32-byte message hash and a corresponding + * signature along with v recovery byte. Takes in an additional flag to check for + * malleability of the signature which is generally only ideal for transactions. + * + * @param hash - 32-byte message hash + * @param sig - signature + * @param v - number of recovery byte + * @param malleabilityFlag - whether to check malleability + * @returns 64 bytes representing the public key if the recovery was successful. + */ export function ecrecover( hash: Bytes, sig: Bytes, @@ -698,36 +729,96 @@ export function ecrecover( // NOTE: "env.panic(msg)" is not exported, use "throw Error(msg)" instead +/** + * Panic the transaction execution with given message + * @param msg - panic message in raw bytes, which should be a valid UTF-8 sequence + */ export function panicUtf8(msg: Bytes): never { env.panic_utf8(msg); } +/** + * Log the message in transaction logs + * @param msg - message in raw bytes, which should be a valid UTF-8 sequence + */ export function logUtf8(msg: Bytes) { env.log_utf8(msg); } +/** + * Log the message in transaction logs + * @param msg - message in raw bytes, which should be a valid UTF-16 sequence + */ export function logUtf16(msg: Bytes) { env.log_utf16(msg); } +/** + * Returns the number of staked NEAR of given validator, in yoctoNEAR + * @param accountId - validator's AccountID + * @returns - staked amount + */ export function validatorStake(accountId: Bytes): bigint { return env.validator_stake(accountId); } +/** + * Returns the number of staked NEAR of all validators, in yoctoNEAR + * @returns total staked amount + */ export function validatorTotalStake(): bigint { return env.validator_total_stake(); } +/** + * Computes multiexp on alt_bn128 curve using Pippenger's algorithm \sum_i + * mul_i g_{1 i} should be equal result. + * + * @param value - equence of (g1:G1, fr:Fr), where + * G1 is point (x:Fq, y:Fq) on alt_bn128, + * alt_bn128 is Y^2 = X^3 + 3 curve over Fq. + * `value` is encoded as packed, little-endian + * `[((u256, u256), u256)]` slice. + * + * @returns multi exp sum + */ export function altBn128G1Multiexp(value: Bytes): Bytes { env.alt_bn128_g1_multiexp(value, 0); return env.read_register(0); } +/** + * Computes sum for signed g1 group elements on alt_bn128 curve \sum_i + * (-1)^{sign_i} g_{1 i} should be equal result. + * + * @param value - sequence of (sign:bool, g1:G1), where + * G1 is point (x:Fq, y:Fq) on alt_bn128, + * alt_bn128 is Y^2 = X^3 + 3 curve over Fq. + * value` is encoded a as packed, little-endian + * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice. + * + * @returns sum over Fq. + */ export function altBn128G1Sum(value: Bytes): Bytes { env.alt_bn128_g1_sum(value, 0); return env.read_register(0); } +/** + * Computes pairing check on alt_bn128 curve. + * \sum_i e(g_{1 i}, g_{2 i}) should be equal one (in additive notation), e(g1, g2) is Ate pairing + * + * @param value - sequence of (g1:G1, g2:G2), where + * G2 is Fr-ordered subgroup point (x:Fq2, y:Fq2) on alt_bn128 twist, + * alt_bn128 twist is Y^2 = X^3 + 3/(i+9) curve over Fq2 + * Fq2 is complex field element (re: Fq, im: Fq) + * G1 is point (x:Fq, y:Fq) on alt_bn128, + * alt_bn128 is Y^2 = X^3 + 3 curve over Fq + * `value` is encoded a as packed, little-endian + * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice. + * + * @returns whether pairing check pass + */ export function altBn128PairingCheck(value: Bytes): boolean { return env.alt_bn128_pairing_check(value) === 1n; }