@alephium/web3 0.15.1 → 0.16.1

package/src/api/api-explorer.ts

@@ -43,6 +43,15 @@ export interface AddressInfo {
   txNumber: number
 }
 
+export interface AddressTokenBalance {
+  /** @format 32-byte-hash */
+  tokenId: string
+  /** @format uint256 */
+  balance: string
+  /** @format uint256 */
+  lockedBalance: string
+}
+
 export interface AssetOutput {
   /** @format int32 */
   hint: number
@@ -71,9 +80,9 @@ export interface BlockEntryLite {
   hash: string
   /** @format int64 */
   timestamp: number
-  /** @format int32 */
+  /** @format group-index */
   chainFrom: number
-  /** @format int32 */
+  /** @format group-index */
   chainTo: number
   /** @format int32 */
   height: number
@@ -121,6 +130,10 @@ export interface Event {
 export interface ExplorerInfo {
   releaseVersion: string
   commit: string
+  /** @format int32 */
+  migrationsVersion: number
+  /** @format int64 */
+  lastFinalizedInputTime: number
 }
 
 export interface Hashrate {
@@ -166,9 +179,9 @@ export interface LogbackValue {
 export interface MempoolTransaction {
   /** @format 32-byte-hash */
   hash: string
-  /** @format int32 */
+  /** @format group-index */
   chainFrom: number
-  /** @format int32 */
+  /** @format group-index */
   chainTo: number
   inputs?: Input[]
   outputs?: Output[]
@@ -197,9 +210,9 @@ export interface OutputRef {
 export interface PendingTransaction {
   /** @format 32-byte-hash */
   hash: string
-  /** @format int32 */
+  /** @format group-index */
   chainFrom: number
-  /** @format int32 */
+  /** @format group-index */
   chainTo: number
   inputs?: Input[]
   outputs?: Output[]
@@ -630,8 +643,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -695,8 +706,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -727,8 +736,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       data?: string[],
       params: RequestParams = {}
@@ -773,8 +780,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -854,8 +859,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -888,8 +891,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -909,13 +910,50 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
      * @request GET:/addresses/{address}/tokens/{token_id}/balance
      */
     getAddressesAddressTokensTokenIdBalance: (address: string, tokenId: string, params: RequestParams = {}) =>
-      this.request<AddressBalance, BadRequest | Unauthorized | NotFound | InternalServerError | ServiceUnavailable>({
+      this.request<
+        AddressTokenBalance,
+        BadRequest | Unauthorized | NotFound | InternalServerError | ServiceUnavailable
+      >({
         path: `/addresses/${address}/tokens/${tokenId}/balance`,
         method: 'GET',
         format: 'json',
         ...params
       }).then(convertHttpResponse),
 
+    /**
+     * @description Get address tokens with balance
+     *
+     * @tags Addresses
+     * @name GetAddressesAddressTokensBalance
+     * @request GET:/addresses/{address}/tokens-balance
+     */
+    getAddressesAddressTokensBalance: (
+      address: string,
+      query?: {
+        /**
+         * Page number
+         * @format int32
+         */
+        page?: number
+        /**
+         * Number of items per page
+         * @format int32
+         */
+        limit?: number
+      },
+      params: RequestParams = {}
+    ) =>
+      this.request<
+        AddressTokenBalance[],
+        BadRequest | Unauthorized | NotFound | InternalServerError | ServiceUnavailable
+      >({
+        path: `/addresses/${address}/tokens-balance`,
+        method: 'GET',
+        query: query,
+        format: 'json',
+        ...params
+      }).then(convertHttpResponse),
+
     /**
      * @description Are the addresses used (at least 1 transaction)
      *
@@ -1046,8 +1084,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -1171,8 +1207,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -1207,8 +1241,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -1240,8 +1272,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -1389,8 +1419,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -1423,8 +1451,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>
@@ -1472,8 +1498,6 @@ export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDa
          * @format int32
          */
         limit?: number
-        /** Reverse pagination */
-        reverse?: boolean
       },
       params: RequestParams = {}
     ) =>

package/src/api/types.ts

@@ -16,7 +16,7 @@ You should have received a copy of the GNU Lesser General Public License
 along with the library. If not, see <http://www.gnu.org/licenses/>.
 */
 
-import { assertType, bs58, Eq } from '../utils'
+import { assertType, bs58, Eq, isBase58, isHexString } from '../utils'
 import * as node from './api-alephium'
 
 export type Number256 = bigint | string
@@ -58,10 +58,15 @@ export function toApiNumber256(v: Val): string {
   if ((typeof v === 'number' && Number.isInteger(v)) || typeof v === 'bigint') {
     return v.toString()
   } else if (typeof v === 'string') {
-    return v
-  } else {
-    throw new Error(`Invalid 256 bit number: ${v}`)
+    try {
+      if (BigInt(v).toString() === v) {
+        return v
+      }
+    } catch (_) {
+      throw new Error(`Invalid value: ${v}, expected a 256 bit number`)
+    }
   }
+  throw new Error(`Invalid value: ${v}, expected a 256 bit number`)
 }
 
 export function toApiNumber256Optional(v?: Val): string | undefined {
@@ -72,9 +77,12 @@ export function fromApiNumber256(n: string): bigint {
   return BigInt(n)
 }
 
-// TODO: check hex string
 export function toApiByteVec(v: Val): string {
-  if (typeof v === 'string') {
+  if (typeof v !== 'string') {
+    throw new Error(`Invalid value: ${v}, expected a hex-string`)
+  }
+  if (isHexString(v)) return v
+  if (isBase58(v)) {
     // try to convert from address to contract id
     try {
       const address = bs58.decode(v)
@@ -82,12 +90,10 @@ export function toApiByteVec(v: Val): string {
         return Buffer.from(address.slice(1)).toString('hex')
       }
     } catch (_) {
-      return v as string
+      throw new Error(`Invalid hex-string: ${v}`)
     }
-    return v as string
-  } else {
-    throw new Error(`Invalid string: ${v}`)
   }
+  throw new Error(`Invalid hex-string: ${v}`)
 }
 
 export function toApiAddress(v: Val): string {
@@ -99,7 +105,7 @@ export function toApiAddress(v: Val): string {
       throw new Error(`Invalid base58 string: ${v}`)
     }
   } else {
-    throw new Error(`Invalid string: ${v}`)
+    throw new Error(`Invalid value: ${v}, expected a base58 string`)
   }
 }
 

package/src/api/utils.ts

@@ -17,6 +17,7 @@ along with the library. If not, see <http://www.gnu.org/licenses/>.
 */
 
 import 'cross-fetch/polyfill'
+import { node } from '..'
 
 export function convertHttpResponse<T>(response: { status: number; data: T; error?: { detail: string } }): T {
   if (response.error) {
@@ -26,3 +27,27 @@ export function convertHttpResponse<T>(response: { status: number; data: T; erro
     return response.data
   }
 }
+
+export function isBalanceEqual(b0: node.Balance, b1: node.Balance): boolean {
+  const isTokenBalanceEqual = (tokens0?: node.Token[], tokens1?: node.Token[]): boolean => {
+    const tokens0Size = tokens0?.length ?? 0
+    const tokens1Size = tokens1?.length ?? 0
+    if (tokens0Size !== tokens1Size) return false
+    if (tokens0Size === 0) return true
+    const _tokens1 = tokens1!.map((t) => ({ ...t, used: false }))
+    return tokens0!.every((t0) => {
+      const t1 = _tokens1.find((t) => !t.used && t0.id === t.id && t0.amount === t.amount)
+      if (t1 === undefined) return false
+      t1.used = true
+      return true
+    })
+  }
+
+  const isAlphBalanceEqual = b0.balance === b1.balance && b0.lockedBalance === b1.lockedBalance
+  return (
+    b0.utxoNum === b1.utxoNum &&
+    isAlphBalanceEqual &&
+    isTokenBalanceEqual(b0.tokenBalances, b1.tokenBalances) &&
+    isTokenBalanceEqual(b0.lockedTokenBalances, b1.lockedTokenBalances)
+  )
+}

package/src/contract/contract.ts

@@ -1040,7 +1040,11 @@ export class Contract extends Artifact {
   }
 
   buildByteCodeToDeploy(initialFields: Fields): string {
-    return ralph.buildContractByteCode(this.bytecode, initialFields, this.fieldsSig)
+    try {
+      return ralph.buildContractByteCode(this.bytecode, initialFields, this.fieldsSig)
+    } catch (error) {
+      throw new Error(`Failed to build bytecode for contract ${this.name}, error: ${error}`)
+    }
   }
 
   static fromApiEvents(
@@ -1186,7 +1190,11 @@ export class Script extends Artifact {
   }
 
   buildByteCodeToDeploy(initialFields: Fields): string {
-    return ralph.buildScriptByteCode(this.bytecodeTemplate, initialFields, this.fieldsSig)
+    try {
+      return ralph.buildScriptByteCode(this.bytecodeTemplate, initialFields, this.fieldsSig)
+    } catch (error) {
+      throw new Error(`Failed to build bytecode for script ${this.name}, error: ${error}`)
+    }
   }
 }
 

package/src/contract/ralph.ts

@@ -17,7 +17,7 @@ along with the library. If not, see <http://www.gnu.org/licenses/>.
 */
 
 import { Buffer } from 'buffer/'
-import { Val } from '../api'
+import { Val, toApiAddress, toApiBoolean, toApiByteVec, toApiNumber256 } from '../api'
 import { bs58, isHexString } from '../utils'
 import { Fields, FieldsSig } from './contract'
 
@@ -197,38 +197,24 @@ export function encodeScriptFieldAsString(tpe: string, value: Val): string {
   return Buffer.from(encodeScriptField(tpe, value)).toString('hex')
 }
 
+// TODO: support array type
 export function encodeScriptField(tpe: string, value: Val): Uint8Array {
   switch (tpe) {
     case 'Bool':
-      if (typeof value === 'boolean') {
-        const byte = value ? Instruction.trueConst : Instruction.falseConst
-        return new Uint8Array([byte])
-      }
-      break
+      const byte = toApiBoolean(value) ? Instruction.trueConst : Instruction.falseConst
+      return new Uint8Array([byte])
     case 'I256':
-      if (typeof value === 'number' && Number.isInteger(value)) {
-        return encodeScriptFieldI256(BigInt(value))
-      } else if (typeof value === 'bigint') {
-        return encodeScriptFieldI256(value)
-      }
-      break
+      const i256 = toApiNumber256(value)
+      return encodeScriptFieldI256(BigInt(i256))
     case 'U256':
-      if (typeof value === 'number' && Number.isInteger(value)) {
-        return encodeScriptFieldU256(BigInt(value))
-      } else if (typeof value === 'bigint') {
-        return encodeScriptFieldU256(value)
-      }
-      break
+      const u256 = toApiNumber256(value)
+      return encodeScriptFieldU256(BigInt(u256))
     case 'ByteVec':
-      if (typeof value === 'string') {
-        return new Uint8Array([Instruction.bytesConst, ...encodeByteVec(value)])
-      }
-      break
+      const hexStr = toApiByteVec(value)
+      return new Uint8Array([Instruction.bytesConst, ...encodeByteVec(hexStr)])
     case 'Address':
-      if (typeof value === 'string') {
-        return new Uint8Array([Instruction.addressConst, ...encodeAddress(value)])
-      }
-      break
+      const address = toApiAddress(value)
+      return new Uint8Array([Instruction.addressConst, ...encodeAddress(address)])
   }
 
   throw invalidScriptField(tpe, value)
@@ -242,13 +228,24 @@ export function buildScriptByteCode(bytecodeTemplate: string, fields: Fields, fi
     const fieldType = fieldsSig.types[`${fieldIndex}`]
     if (fieldName in fields) {
       const fieldValue = fields[`${fieldName}`]
-      return encodeScriptFieldAsString(fieldType, fieldValue)
+      return _encodeField(fieldName, () => encodeScriptFieldAsString(fieldType, fieldValue))
     } else {
       throw new Error(`The value of field ${fieldName} is not provided`)
     }
   })
 }
 
+function _encodeField<T>(fieldName: string, encodeFunc: () => T): T {
+  try {
+    return encodeFunc()
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Invalid ${fieldName}, error: ${error.message}`)
+    }
+    throw error
+  }
+}
+
 function encodeFields(fields: Fields, fieldsSig: FieldsSig, mutable: boolean) {
   const fieldIndexes = fieldsSig.isMutable
     .map((_, index) => index)
@@ -258,7 +255,7 @@ function encodeFields(fields: Fields, fieldsSig: FieldsSig, mutable: boolean) {
     const fieldType = fieldsSig.types[`${fieldIndex}`]
     if (fieldName in fields) {
       const fieldValue = fields[`${fieldName}`]
-      return encodeContractField(fieldType, fieldValue)
+      return _encodeField(fieldName, () => encodeContractField(fieldType, fieldValue))
     } else {
       throw new Error(`The value of field ${fieldName} is not provided`)
     }
@@ -311,46 +308,25 @@ function encodeContractFieldArray(tpe: string, val: Val): Uint8Array[] {
 export function encodeContractField(tpe: string, value: Val): Uint8Array[] {
   switch (tpe) {
     case 'Bool':
-      if (typeof value === 'boolean') {
-        const byte = value ? 1 : 0
-        return [new Uint8Array([ApiValType.Bool, byte])]
-      }
-      break
+      const byte = toApiBoolean(value) ? 1 : 0
+      return [new Uint8Array([ApiValType.Bool, byte])]
     case 'I256':
-      if (typeof value === 'number' && Number.isInteger(value)) {
-        return [encodeContractFieldI256(BigInt(value))]
-      } else if (typeof value === 'bigint') {
-        return [encodeContractFieldI256(value)]
-      }
-      break
+      const i256 = toApiNumber256(value)
+      return [encodeContractFieldI256(BigInt(i256))]
     case 'U256':
-      if (typeof value === 'number' && Number.isInteger(value)) {
-        return [encodeContractFieldU256(BigInt(value))]
-      } else if (typeof value === 'bigint') {
-        return [encodeContractFieldU256(value)]
-      }
-      break
+      const u256 = toApiNumber256(value)
+      return [encodeContractFieldU256(BigInt(u256))]
     case 'ByteVec':
-      if (typeof value === 'string') {
-        return [new Uint8Array([ApiValType.ByteVec, ...encodeByteVec(value)])]
-      }
-      break
+      const hexStr = toApiByteVec(value)
+      return [new Uint8Array([ApiValType.ByteVec, ...encodeByteVec(hexStr)])]
     case 'Address':
-      if (typeof value === 'string') {
-        return [new Uint8Array([ApiValType.Address, ...encodeAddress(value)])]
-      }
-      break
+      const address = toApiAddress(value)
+      return [new Uint8Array([ApiValType.Address, ...encodeAddress(address)])]
 
     default:
       // Array type
       return encodeContractFieldArray(tpe, value)
   }
-
-  throw invalidVal(tpe, value)
-}
-
-function invalidVal(tpe: string, value: Val): Error {
-  return Error(`Invalid API value ${value} for type ${tpe}`)
 }
 
 export function buildDebugBytecode(bytecode: string, bytecodePatch: string): string {