Introduce DappTransactionBuilder

packages/web3/src/codec/instr-codec.test.ts

@@ -233,4 +233,20 @@ describe('Encode & decode instrs', function () {
       expect(instrCodec.decode(encoded)).toEqual(instr)
     })
   })
+
+  it('should check the numeric bounds', () => {
+    expect(() => instr.toU256(0n)).not.toThrow()
+    expect(() => instr.toU256(1n)).not.toThrow()
+    expect(() => instr.toU256((1n << 256n) - 1n)).not.toThrow()
+    expect(() => instr.toU256(-1n)).toThrow('Invalid u256')
+    expect(() => instr.toU256(1n << 256n)).toThrow('Invalid u256')
+
+    expect(() => instr.toI256(0n)).not.toThrow()
+    expect(() => instr.toI256(-1n)).not.toThrow()
+    expect(() => instr.toI256(1n)).not.toThrow()
+    expect(() => instr.toI256(-(1n << 255n))).not.toThrow()
+    expect(() => instr.toI256((1n << 255n) - 1n)).not.toThrow()
+    expect(() => instr.toI256(1n << 255n)).toThrow('Invalid i256')
+    expect(() => instr.toI256(-(1n << 255n) - 1n)).toThrow('Invalid i256')
+  })
 })

packages/web3/src/codec/instr-codec.ts

@@ -20,7 +20,7 @@ import { ArrayCodec } from './array-codec'
 import { i256Codec, u256Codec, i32Codec } from './compact-int-codec'
 import { ByteString, byteStringCodec, byteStringsCodec } from './bytestring-codec'
 import { LockupScript, lockupScriptCodec } from './lockup-script-codec'
-import { byteCodec, Codec } from './codec'
+import { assert, byteCodec, Codec } from './codec'
 import { intAs4BytesCodec } from './int-as-4bytes-codec'
 import { Reader } from './reader'
 export type Instr =
@@ -1263,3 +1263,58 @@ export class InstrCodec extends Codec<Instr> {
 }
 export const instrCodec = new InstrCodec()
 export const instrsCodec = new ArrayCodec<Instr>(instrCodec)
+
+function checkU256(number: bigint) {
+  if (number < 0n || number >= 2n ** 256n) {
+    throw new Error(`Invalid u256 number: ${number}`)
+  }
+}
+
+export function toU256(number: bigint) {
+  checkU256(number)
+  switch (number) {
+    case 0n:
+      return U256Const0
+    case 1n:
+      return U256Const1
+    case 2n:
+      return U256Const2
+    case 3n:
+      return U256Const3
+    case 4n:
+      return U256Const4
+    case 5n:
+      return U256Const5
+    default:
+      return U256Const(number)
+  }
+}
+
+function checkI256(number: bigint) {
+  const upperBound = 2n ** 255n
+  if (number < -upperBound || number >= upperBound) {
+    throw new Error(`Invalid i256 number: ${number}`)
+  }
+}
+
+export function toI256(number: bigint) {
+  checkI256(number)
+  switch (number) {
+    case 0n:
+      return I256Const0
+    case 1n:
+      return I256Const1
+    case 2n:
+      return I256Const2
+    case 3n:
+      return I256Const3
+    case 4n:
+      return I256Const4
+    case 5n:
+      return I256Const5
+    case -1n:
+      return I256ConstN1
+    default:
+      return I256Const(number)
+  }
+}

packages/web3/src/contract/dapp-tx-builder.ts

@@ -0,0 +1,210 @@
+/*
+Copyright 2018 - 2022 The Alephium Authors
+This file is part of the alephium project.
+
+The library is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+The library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Lesser General Public License for more details.
+
+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 { contractIdFromAddress } from '../address'
+import { Val } from '../api'
+import {
+  AddressConst,
+  ApproveAlph,
+  ApproveToken,
+  BytesConst,
+  CallExternal,
+  ConstFalse,
+  ConstTrue,
+  Dup,
+  Instr,
+  Pop,
+  toI256,
+  toU256,
+  U256Const,
+  Method
+} from '../codec'
+import { LockupScript, lockupScriptCodec } from '../codec/lockup-script-codec'
+import { scriptCodec } from '../codec/script-codec'
+import { ALPH_TOKEN_ID } from '../constants'
+import { TraceableError } from '../error'
+import { SignExecuteScriptTxParams } from '../signer'
+import { base58ToBytes, binToHex, HexString, hexToBinUnsafe, isBase58, isHexString } from '../utils'
+
+export class DappTransactionBuilder {
+  private callerLockupScript: LockupScript
+  private approvedAssets: Map<HexString, bigint>
+  private instrs: Instr[]
+
+  constructor(public readonly callerAddress: string) {
+    try {
+      this.callerLockupScript = lockupScriptCodec.decode(base58ToBytes(this.callerAddress))
+      if (this.callerLockupScript.kind !== 'P2PKH' && this.callerLockupScript.kind !== 'P2SH') {
+        throw new Error(`Expected a P2PKH address or P2SH address`)
+      }
+    } catch (error) {
+      throw new TraceableError(`Invalid caller address: ${callerAddress}`, error)
+    }
+    this.approvedAssets = new Map<HexString, bigint>()
+    this.instrs = []
+  }
+
+  callContract(params: {
+    contractAddress: string
+    methodIndex: number
+    args: Val[]
+    attoAlphAmount?: bigint
+    tokens?: { id: HexString; amount: bigint }[]
+    retLength?: number
+  }) {
+    if (!isBase58(params.contractAddress)) {
+      throw new Error(`Invalid contract address: ${params.contractAddress}, expected a base58 string`)
+    }
+    const contractLockupScript = lockupScriptCodec.decode(base58ToBytes(params.contractAddress))
+    if (contractLockupScript.kind !== 'P2C') {
+      throw new Error(`Invalid contract address: ${params.contractAddress}, expected a P2C address`)
+    }
+
+    if (params.methodIndex < 0) {
+      throw new Error(`Invalid method index: ${params.methodIndex}`)
+    }
+
+    const allTokens = (params.tokens ?? []).concat([{ id: ALPH_TOKEN_ID, amount: params.attoAlphAmount ?? 0n }])
+    const instrs = [
+      ...genApproveAssets(this.callerLockupScript, this.approveTokens(allTokens)),
+      ...genContractCall(params.contractAddress, params.methodIndex, params.args, params.retLength ?? 0)
+    ]
+    this.instrs.push(...instrs)
+    return this
+  }
+
+  getResult(): SignExecuteScriptTxParams {
+    const method: Method = {
+      isPublic: true,
+      usePreapprovedAssets: this.approvedAssets.size > 0,
+      useContractAssets: false,
+      usePayToContractOnly: false,
+      argsLength: 0,
+      localsLength: 0,
+      returnLength: 0,
+      instrs: this.instrs
+    }
+    const script = { methods: [method] }
+    const bytecode = scriptCodec.encode(script)
+    const tokens = Array.from(this.approvedAssets.entries()).map(([id, amount]) => ({ id, amount }))
+    this.approvedAssets.clear()
+    this.instrs = []
+    return {
+      signerAddress: this.callerAddress,
+      signerKeyType: this.callerLockupScript.kind === 'P2PKH' ? 'default' : 'bip340-schnorr',
+      bytecode: binToHex(bytecode),
+      attoAlphAmount: tokens.find((t) => t.id === ALPH_TOKEN_ID)?.amount,
+      tokens: tokens.filter((t) => t.id !== ALPH_TOKEN_ID)
+    }
+  }
+
+  private addTokenToMap(tokenId: HexString, amount: bigint, map: Map<HexString, bigint>) {
+    const current = map.get(tokenId)
+    if (current !== undefined) {
+      map.set(tokenId, current + amount)
+    } else if (amount > 0n) {
+      map.set(tokenId, amount)
+    }
+  }
+
+  private approveTokens(tokens: { id: HexString; amount: bigint }[]): { id: HexString; amount: bigint }[] {
+    const tokenAmounts = new Map<HexString, bigint>()
+    tokens.forEach((token) => {
+      if (!(isHexString(token.id) && token.id.length === 64)) {
+        throw new Error(`Invalid token id: ${token.id}`)
+      }
+      if (token.amount < 0n) {
+        throw new Error(`Invalid token amount: ${token.amount}`)
+      }
+      this.addTokenToMap(token.id, token.amount, tokenAmounts)
+      this.addTokenToMap(token.id, token.amount, this.approvedAssets)
+    })
+    return Array.from(tokenAmounts.entries()).map(([id, amount]) => ({ id, amount }))
+  }
+}
+
+function genApproveAssets(callerLockupScript: LockupScript, tokens: { id: HexString; amount: bigint }[]): Instr[] {
+  if (tokens.length === 0) {
+    return []
+  }
+  const approveInstrs = tokens.flatMap((token) => {
+    if (token.id === ALPH_TOKEN_ID) {
+      return [U256Const(token.amount), ApproveAlph]
+    } else {
+      const tokenId = BytesConst(hexToBinUnsafe(token.id))
+      return [tokenId, U256Const(token.amount), ApproveToken]
+    }
+  })
+  return [
+    AddressConst(callerLockupScript),
+    ...Array.from(Array(tokens.length - 1).keys()).map(() => Dup),
+    ...approveInstrs
+  ]
+}
+
+function bigintToNumeric(value: bigint): Instr {
+  return value >= 0 ? toU256(value) : toI256(value)
+}
+
+function strToNumeric(str: string): Instr {
+  const regex = /^-?\d+[ui]?$/
+  if (regex.test(str)) {
+    if (str.endsWith('i')) return toI256(BigInt(str.slice(0, str.length - 1)))
+    if (str.endsWith('u')) return toU256(BigInt(str.slice(0, str.length - 1)))
+    return bigintToNumeric(BigInt(str))
+  }
+  throw new Error(`Invalid number: ${str}`)
+}
+
+function toAddressOpt(str: string): LockupScript | undefined {
+  if (!isBase58(str)) return undefined
+  try {
+    return lockupScriptCodec.decode(base58ToBytes(str))
+  } catch (_) {
+    return undefined
+  }
+}
+
+export function genArgs(args: Val[]): Instr[] {
+  return args.flatMap((arg) => {
+    if (typeof arg === 'boolean') return arg ? [ConstTrue] : [ConstFalse]
+    if (typeof arg === 'bigint') return bigintToNumeric(arg)
+    if (typeof arg === 'string') {
+      if (isHexString(arg)) return [BytesConst(hexToBinUnsafe(arg))]
+      const addressOpt = toAddressOpt(arg)
+      if (addressOpt !== undefined) return AddressConst(addressOpt)
+      return strToNumeric(arg)
+    }
+    if (Array.isArray(arg)) return genArgs(arg)
+    if (arg instanceof Map) throw new Error(`Map cannot be used as a function argument`)
+    if (typeof arg === 'object') return genArgs(Object.values(arg))
+    throw new Error(`Unknown argument type: ${typeof arg}, arg: ${arg}`)
+  })
+}
+
+function genContractCall(contractAddress: string, methodIndex: number, args: Val[], retLength: number): Instr[] {
+  const argInstrs = genArgs(args)
+  return [
+    ...argInstrs,
+    toU256(BigInt(argInstrs.length)),
+    toU256(BigInt(retLength)),
+    BytesConst(contractIdFromAddress(contractAddress)),
+    CallExternal(methodIndex),
+    ...Array.from(Array(retLength).keys()).map(() => Pop)
+  ]
+}

packages/web3/src/contract/index.ts

@@ -21,3 +21,4 @@ export * from './contract'
 export * from './events'
 export * from './script-simulator'
 export * from './deployment'
+export { DappTransactionBuilder } from './dapp-tx-builder'

packages/web3/src/contract/ralph.ts

@@ -26,24 +26,11 @@ import {
   ConstFalse,
   ConstTrue,
   i256Codec,
-  I256Const,
-  I256Const0,
-  I256Const1,
-  I256Const2,
-  I256Const3,
-  I256Const4,
-  I256Const5,
-  I256ConstN1,
   i32Codec,
   instrCodec,
   u256Codec,
-  U256Const,
-  U256Const0,
-  U256Const1,
-  U256Const2,
-  U256Const3,
-  U256Const4,
-  U256Const5
+  toU256,
+  toI256
 } from '../codec'
 import { boolCodec } from '../codec/codec'
 import { TraceableError } from '../error'
@@ -118,43 +105,11 @@ function invalidScriptField(tpe: string, value: Val): Error {
 }
 
 function encodeScriptFieldI256(value: bigint): Uint8Array {
-  switch (value) {
-    case 0n:
-      return instrCodec.encode(I256Const0)
-    case 1n:
-      return instrCodec.encode(I256Const1)
-    case 2n:
-      return instrCodec.encode(I256Const2)
-    case 3n:
-      return instrCodec.encode(I256Const3)
-    case 4n:
-      return instrCodec.encode(I256Const4)
-    case 5n:
-      return instrCodec.encode(I256Const5)
-    case -1n:
-      return instrCodec.encode(I256ConstN1)
-    default:
-      return instrCodec.encode(I256Const(value))
-  }
+  return instrCodec.encode(toI256(value))
 }
 
 function encodeScriptFieldU256(value: bigint): Uint8Array {
-  switch (value) {
-    case 0n:
-      return instrCodec.encode(U256Const0)
-    case 1n:
-      return instrCodec.encode(U256Const1)
-    case 2n:
-      return instrCodec.encode(U256Const2)
-    case 3n:
-      return instrCodec.encode(U256Const3)
-    case 4n:
-      return instrCodec.encode(U256Const4)
-    case 5n:
-      return instrCodec.encode(U256Const5)
-    default:
-      return instrCodec.encode(U256Const(value))
-  }
+  return instrCodec.encode(toU256(value))
 }
 
 export function encodeScriptFieldAsString(tpe: string, value: Val): string {