@alephium/web3 0.0.1-test.0

package/src/signer/signer.ts

@@ -0,0 +1,313 @@
+/*
+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 { ec as EC } from 'elliptic'
+import { NodeProvider } from '../api'
+import { node } from '../api'
+import * as utils from '../utils'
+import { Eq, assertType } from '../utils'
+import blake from 'blakejs'
+import { Token } from '../api/api-alephium'
+
+const ec = new EC('secp256k1')
+
+export interface SignResult {
+  fromGroup: number
+  toGroup: number
+  unsignedTx: string
+  txId: string
+  signature: string
+}
+
+export interface Account {
+  address: string
+  group: number
+  publicKey: string
+}
+
+export type SubmitTx = { submitTx?: boolean }
+export type SignerAddress = { signerAddress: string }
+type TxBuildParams<T> = Omit<T, 'fromPublicKey'> & SignerAddress & SubmitTx
+
+export type GetAccountsParams = undefined
+export type GetAccountsResult = Account[]
+
+export interface SignTransferTxParams {
+  signerAddress: string
+  destinations: node.Destination[]
+  utxos?: node.OutputRef[]
+  gasAmount?: number
+  gasPrice?: string
+  submitTx?: boolean
+}
+assertType<Eq<SignTransferTxParams, TxBuildParams<node.BuildTransaction>>>()
+export interface SignTransferTxResult {
+  fromGroup: number
+  toGroup: number
+  unsignedTx: string
+  txId: string
+  signature: string
+}
+assertType<Eq<SignTransferTxResult, SignResult>>()
+
+export interface SignDeployContractTxParams {
+  signerAddress: string
+  bytecode: string
+  initialAttoAlphAmount?: string
+  initialTokenAmounts?: Token[]
+  issueTokenAmount?: string
+  gasAmount?: number
+  gasPrice?: string
+  submitTx?: boolean
+}
+assertType<Eq<SignDeployContractTxParams, TxBuildParams<node.BuildDeployContractTx>>>()
+export interface SignDeployContractTxResult {
+  fromGroup: number
+  toGroup: number
+  unsignedTx: string
+  txId: string
+  signature: string
+  contractId: string
+  contractAddress: string
+}
+assertType<Eq<SignDeployContractTxResult, SignResult & { contractId: string; contractAddress: string }>>()
+
+export interface SignExecuteScriptTxParams {
+  signerAddress: string
+  bytecode: string
+  attoAlphAmount?: string
+  tokens?: node.Token[]
+  gasAmount?: number
+  gasPrice?: string
+  submitTx?: boolean
+}
+assertType<Eq<SignExecuteScriptTxParams, TxBuildParams<node.BuildExecuteScriptTx>>>()
+export interface SignExecuteScriptTxResult {
+  fromGroup: number
+  toGroup: number
+  unsignedTx: string
+  txId: string
+  signature: string
+}
+assertType<Eq<SignExecuteScriptTxResult, SignResult>>()
+
+export interface SignUnsignedTxParams {
+  signerAddress: string
+  unsignedTx: string
+  submitTx?: boolean
+}
+assertType<Eq<SignUnsignedTxParams, { unsignedTx: string } & SubmitTx & SignerAddress>>()
+export interface SignUnsignedTxResult {
+  fromGroup: number
+  toGroup: number
+  unsignedTx: string
+  txId: string
+  signature: string
+}
+assertType<Eq<SignUnsignedTxResult, SignResult>>()
+
+export interface SignHexStringParams {
+  signerAddress: string
+  hexString: string
+}
+assertType<Eq<SignHexStringParams, { hexString: string } & SignerAddress>>()
+export interface SignHexStringResult {
+  signature: string
+}
+assertType<Eq<SignHexStringResult, Pick<SignResult, 'signature'>>>()
+
+export interface SignMessageParams {
+  signerAddress: string
+  message: string
+}
+assertType<Eq<SignMessageParams, { message: string } & SignerAddress>>()
+export interface SignMessageResult {
+  signature: string
+}
+assertType<Eq<SignMessageResult, Pick<SignResult, 'signature'>>>()
+
+export interface SignerProvider {
+  getAccounts(): Promise<Account[]>
+  signTransferTx(params: SignTransferTxParams): Promise<SignTransferTxResult>
+  signDeployContractTx(params: SignDeployContractTxParams): Promise<SignDeployContractTxResult>
+  signExecuteScriptTx(params: SignExecuteScriptTxParams): Promise<SignExecuteScriptTxResult>
+  signUnsignedTx(params: SignUnsignedTxParams): Promise<SignUnsignedTxResult>
+  signHexString(params: SignHexStringParams): Promise<SignHexStringResult>
+  signMessage(params: SignMessageParams): Promise<SignMessageResult>
+}
+
+export abstract class SignerWithNodeProvider implements SignerProvider {
+  readonly provider: NodeProvider
+  alwaysSubmitTx: boolean
+
+  abstract getAccounts(): Promise<Account[]>
+
+  async getAccount(signerAddress: string): Promise<Account> {
+    const accounts = await this.getAccounts()
+    const account = accounts.find((a) => a.address === signerAddress)
+    if (typeof account === 'undefined') {
+      throw new Error('Unmatched signerAddress')
+    } else {
+      return account
+    }
+  }
+
+  constructor(provider: NodeProvider, alwaysSubmitTx: boolean) {
+    this.provider = provider
+    this.alwaysSubmitTx = alwaysSubmitTx
+  }
+
+  private async defaultSignerAddress(): Promise<string> {
+    return (await this.getAccounts())[0].address
+  }
+
+  async submitTransaction(unsignedTx: string, txHash: string, signerAddress?: string): Promise<SubmissionResult> {
+    const address = typeof signerAddress !== 'undefined' ? signerAddress : await this.defaultSignerAddress()
+    const signature = await this.signRaw(address, txHash)
+    const params: node.SubmitTransaction = { unsignedTx: unsignedTx, signature: signature }
+    return this.provider.transactions.postTransactionsSubmit(params)
+  }
+
+  private shouldSubmitTx(params: SubmitTx): boolean {
+    return this.alwaysSubmitTx || (params.submitTx ? params.submitTx : true)
+  }
+
+  private async usePublicKey<T extends SignerAddress>(
+    params: T
+  ): Promise<Omit<T, 'signerAddress'> & { fromPublicKey: string }> {
+    const { signerAddress, ...restParams } = params
+    const allAccounts = await this.getAccounts()
+    const signerAccount = allAccounts.find((account) => account.address === signerAddress)
+    if (typeof signerAccount === 'undefined') {
+      throw new Error('Unknown signer address')
+    } else {
+      return { fromPublicKey: signerAccount.publicKey, ...restParams }
+    }
+  }
+
+  async signTransferTx(params: SignTransferTxParams): Promise<SignTransferTxResult> {
+    const response = await this.buildTransferTx(params)
+    return this.handleSign({ signerAddress: params.signerAddress, ...response }, this.shouldSubmitTx(params))
+  }
+
+  async buildTransferTx(params: SignTransferTxParams): Promise<node.BuildTransactionResult> {
+    return this.provider.transactions.postTransactionsBuild(await this.usePublicKey(params))
+  }
+
+  async signDeployContractTx(params: SignDeployContractTxParams): Promise<SignDeployContractTxResult> {
+    const response = await this.buildContractCreationTx(params)
+    const result = await this.handleSign(
+      { signerAddress: params.signerAddress, ...response },
+      this.shouldSubmitTx(params)
+    )
+    const contractId = utils.binToHex(utils.contractIdFromAddress(response.contractAddress))
+    return { ...result, contractId: contractId, contractAddress: response.contractAddress }
+  }
+
+  async buildContractCreationTx(params: SignDeployContractTxParams): Promise<node.BuildDeployContractTxResult> {
+    return this.provider.contracts.postContractsUnsignedTxDeployContract(await this.usePublicKey(params))
+  }
+
+  async signExecuteScriptTx(params: SignExecuteScriptTxParams): Promise<SignExecuteScriptTxResult> {
+    const response = await this.buildScriptTx(params)
+    return this.handleSign({ signerAddress: params.signerAddress, ...response }, this.shouldSubmitTx(params))
+  }
+
+  async buildScriptTx(params: SignExecuteScriptTxParams): Promise<node.BuildExecuteScriptTxResult> {
+    return this.provider.contracts.postContractsUnsignedTxExecuteScript(await this.usePublicKey(params))
+  }
+
+  // in general, wallet should show the decoded information to user for confirmation
+  // please overwrite this function for real wallet
+  async signUnsignedTx(params: SignUnsignedTxParams): Promise<SignUnsignedTxResult> {
+    const data = { unsignedTx: params.unsignedTx }
+    const decoded = await this.provider.transactions.postTransactionsDecodeUnsignedTx(data)
+    return this.handleSign(
+      {
+        fromGroup: decoded.fromGroup,
+        toGroup: decoded.toGroup,
+        signerAddress: params.signerAddress,
+        unsignedTx: params.unsignedTx,
+        txId: decoded.unsignedTx.txId
+      },
+      params.submitTx ? params.submitTx : true // we don't consider `alwaysSubmitTx` as the tx might needs multiple signatures
+    )
+  }
+
+  protected async handleSign(
+    response: { fromGroup: number; toGroup: number; signerAddress: string; unsignedTx: string; txId: string },
+    submitTx: boolean
+  ): Promise<SignResult> {
+    // sign the tx
+    const signature = await this.signRaw(response.signerAddress, response.txId)
+    // submit the tx if required
+    if (submitTx) {
+      await this.provider.transactions.postTransactionsSubmit({
+        unsignedTx: response.unsignedTx,
+        signature: signature
+      })
+    }
+    // return the signature back to the provider
+    return {
+      fromGroup: response.fromGroup,
+      toGroup: response.toGroup,
+      unsignedTx: response.unsignedTx,
+      txId: response.txId,
+      signature: signature
+    }
+  }
+
+  async signHexString(params: SignHexStringParams): Promise<SignHexStringResult> {
+    const signature = await this.signRaw(params.signerAddress, params.hexString)
+    return { signature: signature }
+  }
+
+  async signMessage(params: SignMessageParams): Promise<SignMessageResult> {
+    const extendedMessage = extendMessage(params.message)
+    const messageHash = blake.blake2b(extendedMessage, undefined, 32)
+    const signature = await this.signRaw(params.signerAddress, utils.binToHex(messageHash))
+    return { signature: signature }
+  }
+
+  abstract signRaw(signerAddress: string, hexString: string): Promise<string>
+}
+
+export interface SubmissionResult {
+  txId: string
+  fromGroup: number
+  toGroup: number
+}
+
+export function verifyHexString(hexString: string, publicKey: string, signature: string): boolean {
+  try {
+    const key = ec.keyFromPublic(publicKey, 'hex')
+    return key.verify(hexString, utils.signatureDecode(ec, signature))
+  } catch (error) {
+    return false
+  }
+}
+
+function extendMessage(message: string): string {
+  return 'Alephium Signed Message: ' + message
+}
+
+export function verifySignedMessage(message: string, publicKey: string, signature: string): boolean {
+  const extendedMessage = extendMessage(message)
+  const messageHash = blake.blake2b(extendedMessage, undefined, 32)
+  return verifyHexString(utils.binToHex(messageHash), publicKey, signature)
+}

package/src/test/index.ts

@@ -0,0 +1,32 @@
+/*
+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 { NodeProvider } from '../api'
+import { NodeWallet } from '../signer'
+
+export const testWalletName = 'alephium-web3-test-only-wallet'
+export const testAddress = '1DrDyTr9RpRsQnDnXo2YRiPzPW4ooHX5LLoqXrqfMrpQH'
+export const testPassword = 'alph'
+
+export async function testWallet(provider: NodeProvider): Promise<NodeWallet> {
+  const wallet = new NodeWallet(provider, testWalletName)
+  await wallet.unlock(testPassword)
+  return wallet
+}
+
+export * from './privatekey-wallet'

package/src/test/privatekey-wallet.ts

@@ -0,0 +1,58 @@
+/*
+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 { ec as EC } from 'elliptic'
+import { NodeProvider } from '../api'
+import { Account, SignerWithNodeProvider } from '../signer'
+import * as utils from '../utils'
+
+const ec = new EC('secp256k1')
+
+export class PrivateKeyWallet extends SignerWithNodeProvider {
+  readonly privateKey: string
+  readonly publicKey: string
+  readonly address: string
+  readonly group: number
+
+  constructor(provider: NodeProvider, privateKey: string, alwaysSubmitTx = true) {
+    super(provider, alwaysSubmitTx)
+    this.privateKey = privateKey
+    this.publicKey = utils.publicKeyFromPrivateKey(privateKey)
+    this.address = utils.addressFromPublicKey(this.publicKey)
+    this.group = utils.groupOfAddress(this.address)
+  }
+
+  static Random(provider: NodeProvider, alwaysSubmitTx = true): PrivateKeyWallet {
+    const keyPair = ec.genKeyPair()
+    return new PrivateKeyWallet(provider, keyPair.getPrivate().toString('hex'), alwaysSubmitTx)
+  }
+
+  async getAccounts(): Promise<Account[]> {
+    return [{ address: this.address, publicKey: this.publicKey, group: this.group }]
+  }
+
+  async signRaw(signerAddress: string, hexString: string): Promise<string> {
+    if (signerAddress !== this.address) {
+      throw Error('Unmatched signer address')
+    }
+
+    const key = ec.keyFromPrivate(this.privateKey)
+    const signature = key.sign(hexString)
+    return utils.signatureEncode(signature)
+  }
+}

package/src/transaction/index.ts

@@ -0,0 +1,20 @@
+/*
+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/>.
+*/
+
+export * from './sign-verify'
+export * from './status'

package/src/transaction/sign-verify.test.ts

@@ -0,0 +1,50 @@
+/*
+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 EC from 'elliptic'
+import assert from 'assert'
+
+import { transactionSign, transactionVerifySignature } from './sign-verify'
+
+describe('transaction', function () {
+  it('should verify signature', () => {
+    const txHash = '8fc5f0d120b730f97f6cea5f02ae4a6ee7bf451d9261c623ea69d85e870201d2'
+    const pubKey = '02625b26ae1c5f7986475009e4037b3e6fe6320fde3c3f3332bea11ecadc35dd13'
+    const txSig =
+      '78471e7c97e558c98ac307ef699ed535ece319102fc69ea416dbb44fbb3cbf9c42dbfbf4ce73eb68c5e0d66122eb25d2ebe1cf9e37ef4c4f4e7a2ed35de141bc'
+    const unnormalizedSig =
+      '78471e7c97e558c98ac307ef699ed535ece319102fc69ea416dbb44fbb3cbf9cbd24040b318c14973a1f299edd14da2bcecd0d48775953ec71582fb97254ff85'
+    const wrongSig =
+      '88471e7c97e558c98ac307ef699ed535ece319102fc69ea416dbb44fbb3cbf9c42dbfbf4ce73eb68c5e0d66122eb25d2ebe1cf9e37ef4c4f4e7a2ed35de141bc'
+
+    assert.strictEqual(transactionVerifySignature(txHash, pubKey, txSig), true)
+    assert.strictEqual(transactionVerifySignature(txHash, pubKey, unnormalizedSig), false)
+    assert.strictEqual(transactionVerifySignature(txHash, pubKey, wrongSig), false)
+  })
+
+  it('should sign and verify signature', () => {
+    const ec = new EC.ec('secp256k1')
+    const key = ec.genKeyPair()
+    const privateKey = key.getPrivate().toString('hex')
+    const publicKey = key.getPublic().encode('hex', true)
+
+    const txHash = '8fc5f0d120b730f97f6cea5f02ae4a6ee7bf451d9261c623ea69d85e870201d2'
+    const signature = transactionSign(txHash, privateKey)
+    assert.strictEqual(transactionVerifySignature(txHash, publicKey, signature), true)
+  })
+})

package/src/transaction/sign-verify.ts

@@ -0,0 +1,39 @@
+/*
+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 { ec as EC } from 'elliptic'
+
+import * as utils from '../utils'
+
+const ec = new EC('secp256k1')
+
+export function transactionSign(txHash: string, privateKey: string): string {
+  const keyPair = ec.keyFromPrivate(privateKey)
+  const signature = keyPair.sign(txHash)
+
+  return utils.signatureEncode(signature)
+}
+
+export function transactionVerifySignature(txHash: string, publicKey: string, signature: string): boolean {
+  try {
+    const key = ec.keyFromPublic(publicKey, 'hex')
+    return key.verify(txHash, utils.signatureDecode(ec, signature))
+  } catch (error) {
+    return false
+  }
+}

package/src/transaction/status.ts

@@ -0,0 +1,58 @@
+/*
+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 { TxStatus } from '../api/api-alephium'
+import { Subscription, SubscribeOptions } from '../utils'
+
+export class TxStatusSubscription extends Subscription<TxStatus> {
+  readonly txId: string
+  readonly fromGroup?: number
+  readonly toGroup?: number
+
+  constructor(options: SubscribeOptions<TxStatus>, txId: string, fromGroup?: number, toGroup?: number) {
+    super(options)
+    this.txId = txId
+    this.fromGroup = fromGroup
+    this.toGroup = toGroup
+
+    this.startPolling()
+  }
+
+  override async polling() {
+    try {
+      const txStatus = await this.provider.transactions.getTransactionsStatus({
+        txId: this.txId,
+        fromGroup: this.fromGroup,
+        toGroup: this.toGroup
+      })
+
+      await this.messageCallback(txStatus)
+    } catch (err) {
+      await this.errorCallback(err, this)
+    }
+  }
+}
+
+export function subscribeToTxStatus(
+  options: SubscribeOptions<TxStatus>,
+  txId: string,
+  fromGroup?: number,
+  toGroup?: number
+): TxStatusSubscription {
+  return new TxStatusSubscription(options, txId, fromGroup, toGroup)
+}

package/src/utils/address.test.ts

@@ -0,0 +1,47 @@
+/*
+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 { addressToGroup } from './address'
+
+describe('address', function () {
+  it('should derive group', async () => {
+    function check(address: string, expected: number) {
+      const group = addressToGroup(address, 4)
+      expect(group).toEqual(expected)
+    }
+
+    check('12psscGPMgdqctaeCA37HYAkpVBFX1LbN4dSvjyxbDyKk', 1)
+    check('16TGLiD3fqyuGFRFHffh58BC3okYCbjRH1WHPzeSp39Wi', 2)
+    check('15aTcpJfCX9akQqYuRMMgun6Mv6ek8bigB98VTUFMwKYA', 1)
+    check('164ejvnxGYRPUt3tYwJrMxBLLmeag2WACH4GfcsRUN3W7', 2)
+    check('15p5vK921GnxFSQgXZo8Wceg6EvwcXZ9rCQxE2SeXc1s5', 1)
+    check('1HSLAetSuMTKPHukvXYg6yaDuUJ67vxGashzFLEuu6qV6', 1)
+    check('1HbU1TDiUMAj33Cp5cA2xc9uTqp1bjWa5UvkeGLm4bDbE', 2)
+    check('13zn4s3fb5Q9d8rtszYdmYVpQ3MM9VM2xLBe9rMhcNxjd', 0)
+    check('1DdQwce5ZzFrEYyz1H5KU9v8hRpoTbq5i7zE5Nu5k4ope', 2)
+    check('19hpcUVGzdpWRD8yVUyP9pJwwxD6P5ixGUgSmVPbhBAVX', 2)
+    check('1DpNeY8uutS1FRW7D565WjUgu5HcKSYAMqZNWgUJWggWZ', 0)
+    check('1G1gjpt4mxij7JwP5SpX6ScwQHisWN3V5WBtFfWKtc3vo', 3)
+    check('19XyGb6f1upjvQAG4vexB1EmY3pU8G2VN5gM267Pdhogg', 3)
+    check('1H5YniQrUqxJY9ShTjMeX6DMgjPpYfdFqDvTgBYv6h1iz', 1)
+    check('18Ca9jZDqRcxTfdNr2hq5KBJjf7PJLA5PXMjRoeB83JNv', 3)
+    check('15XyPNJuZ85wyUMs4mwn98LLPMjiwUSCuTmR74NuxpwXT', 0)
+    check('1F6ssQRwH1p1omaoQR3eirFrycHC3mUr3Vw9pLcgEe33W', 1)
+    check('19JtVnQ4YLcA9mWPafnLmtWarAjdaLR3d7R5RAUjxHbe1', 3)
+  })
+})

package/src/utils/address.ts

@@ -0,0 +1,39 @@
+/*
+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 bs58 from './bs58'
+import djb2 from './djb2'
+
+export function addressToGroup(address: string, totalNumberOfGroups: number): number {
+  const bytes = bs58.decode(address).slice(1)
+  const value = djb2(bytes) | 1
+  const hash = toPosInt(xorByte(value))
+  const group = hash % totalNumberOfGroups
+  return group
+}
+
+function xorByte(value: number): number {
+  const byte0 = value >> 24
+  const byte1 = value >> 16
+  const byte2 = value >> 8
+  return byte0 ^ byte1 ^ byte2 ^ value
+}
+
+function toPosInt(byte: number): number {
+  return byte & 0xff
+}

package/src/utils/bs58.ts

@@ -0,0 +1,26 @@
+/*
+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/>.
+*/
+
+/** This source is under MIT License and come originally from https://github.com/cryptocoinjs/bs58 **/
+import basex from 'base-x'
+
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+export const bs58 = basex(ALPHABET)
+
+export default bs58