@alephium/web3 1.11.5 → 1.12.0-beta.0

package/dist/src/contract/contract.d.ts

@@ -84,7 +84,7 @@ export declare class Contract extends Artifact {
     static DebugEventIndex: number;
     static fromApiEvent(event: node.ContractEventByTxId, codeHash: string | undefined, txId: string, getContractByCodeHash: (codeHash: string) => Contract): ContractEvent;
     fromApiTestContractResult(methodName: string, result: node.TestContractResult, txId: string, getContractByCodeHash: (codeHash: string) => Contract): TestContractResult<unknown>;
-    txParamsForDeployment<P extends Fields>(signer: SignerProvider, params: DeployContractParams<P>): Promise<SignDeployContractTxParams>;
+    txParamsForDeployment<P extends Fields>(signer: SignerProvider, params: DeployContractParams<P>, group?: number): Promise<SignDeployContractTxParams>;
     buildByteCodeToDeploy(initialFields: Fields, isDevnet: boolean, exposePrivateFunctions?: boolean): string;
     static fromApiEvents(events: node.ContractEventByTxId[], addressToCodeHash: Map<string, string>, txId: string, getContractByCodeHash: (codeHash: string) => Contract): ContractEvent[];
     toApiCallContract<T extends Arguments>(params: CallContractParams<T>, groupIndex: number, contractAddress: string, methodIndex: number): node.CallContract;
@@ -132,7 +132,7 @@ export type TestContractParamsWithoutMaps<F extends Fields = Fields, A extends A
 export interface TestContractParams<F extends Fields = Fields, A extends Arguments = Arguments, M extends Record<string, Map<Val, Val>> = Record<string, Map<Val, Val>>> {
     group?: number;
     address?: string;
-    callerAddress?: string;
+    callerContractAddress?: string;
     blockHash?: string;
     blockTimeStamp?: number;
     txId?: string;
@@ -195,7 +195,7 @@ export declare abstract class ContractFactory<I extends ContractInstance, F exte
     readonly contract: Contract;
     constructor(contract: Contract);
     abstract at(address: string): I;
-    deploy(signer: SignerProvider, deployParams: DeployContractParams<F>): Promise<DeployContractResult<I>>;
+    deploy(signer: SignerProvider, deployParams: DeployContractParams<F>, group?: number): Promise<DeployContractResult<I>>;
     deployTemplate(signer: SignerProvider): Promise<DeployContractResult<I>>;
     protected stateForTest_(initFields: F, asset?: Asset, address?: string, maps?: Record<string, Map<Val, Val>>): ContractState<F> | ContractStateWithMaps<F>;
 }

package/dist/src/contract/contract.js

@@ -310,7 +310,7 @@ class Contract extends Artifact {
             blockTimeStamp: params.blockTimeStamp,
             txId: params.txId,
             address: params.address,
-            callerAddress: params.callerAddress,
+            callerContractAddress: params.callerContractAddress,
             bytecode: this.isInlineFunc(methodIndex) ? this.getByteCodeForTesting() : this.bytecodeDebug,
             initialImmFields: immFields,
             initialMutFields: mutFields,
@@ -382,13 +382,20 @@ class Contract extends Artifact {
             debugMessages: result.debugMessages
         };
     }
-    async txParamsForDeployment(signer, params) {
+    async txParamsForDeployment(signer, params, group) {
         const isDevnet = await this.isDevnet(signer);
         const initialFields = params.initialFields ?? {};
         const bytecode = this.buildByteCodeToDeploy(addStdIdToFields(this, initialFields), isDevnet, params.exposePrivateFunctions ?? false);
         const selectedAccount = await signer.getSelectedAccount();
+        let signerAddress = selectedAccount.address;
+        if ((0, address_1.isGrouplessAddressWithoutGroupIndex)(selectedAccount.address)) {
+            if (group === undefined) {
+                throw new Error('Groupless address requires explicit group number for contract deployment');
+            }
+            signerAddress = `${selectedAccount.address}:${group}`;
+        }
         const signerParams = {
-            signerAddress: selectedAccount.address,
+            signerAddress,
             signerKeyType: selectedAccount.keyType,
             bytecode: bytecode,
             initialAttoAlphAmount: params?.initialAttoAlphAmount,
@@ -678,11 +685,11 @@ class ContractFactory {
     constructor(contract) {
         this.contract = contract;
     }
-    async deploy(signer, deployParams) {
+    async deploy(signer, deployParams, group) {
         const signerParams = await this.contract.txParamsForDeployment(signer, {
             ...deployParams,
             initialFields: addStdIdToFields(this.contract, deployParams.initialFields)
-        });
+        }, group);
         const result = await signer.signAndSubmitDeployContractTx(signerParams);
         return {
             ...result,

package/dist/src/contract/ralph.js

@@ -23,6 +23,7 @@ const utils_1 = require("../utils");
 const codec_1 = require("../codec");
 const codec_2 = require("../codec/codec");
 const error_1 = require("../error");
+const address_1 = require("../address");
 function encodeByteVec(hex) {
     if (!(0, utils_1.isHexString)(hex)) {
         throw Error(`Given value ${hex} is not a valid hex string`);
@@ -32,7 +33,7 @@ function encodeByteVec(hex) {
 }
 exports.encodeByteVec = encodeByteVec;
 function encodeAddress(address) {
-    return utils_1.bs58.decode(address);
+    return (0, address_1.addressToBytes)(address);
 }
 exports.encodeAddress = encodeAddress;
 var VmValType;

package/dist/src/signer/signer.js

@@ -240,6 +240,6 @@ function toApiDestinations(data) {
 }
 exports.toApiDestinations = toApiDestinations;
 function fromApiDestination(data) {
-    return { ...data, attoAlphAmount: (0, api_1.fromApiNumber256)(data.attoAlphAmount), tokens: (0, api_1.fromApiTokens)(data.tokens) };
+    return { ...data, attoAlphAmount: (0, api_1.fromApiNumber256)(data.attoAlphAmount ?? '0'), tokens: (0, api_1.fromApiTokens)(data.tokens) };
 }
 exports.fromApiDestination = fromApiDestination;

package/dist/src/signer/tx-builder.d.ts

@@ -1,5 +1,5 @@
 import { NodeProvider } from '../api';
-import { SignChainedTxParams, SignChainedTxResult, SignDeployContractTxParams, SignDeployContractTxResult, SignExecuteScriptTxParams, SignExecuteScriptTxResult, SignTransferTxParams, SignTransferTxResult, SignUnsignedTxParams, SignUnsignedTxResult } from './types';
+import { SignChainedTxParams, SignChainedTxResult, SignDeployContractTxParams, SignDeployContractTxResult, SignExecuteScriptTxParams, SignExecuteScriptTxResult, SignTransferTxParams, SignTransferTxResult, SignUnsignedTxParams, SignUnsignedTxResult, SignGrouplessTransferTxParams, SignGrouplessDeployContractTxParams, SignGrouplessExecuteScriptTxParams } from './types';
 export declare abstract class TransactionBuilder {
     abstract get nodeProvider(): NodeProvider;
     static from(nodeProvider: NodeProvider): TransactionBuilder;
@@ -9,8 +9,14 @@ export declare abstract class TransactionBuilder {
     buildDeployContractTx(params: SignDeployContractTxParams, publicKey: string): Promise<Omit<SignDeployContractTxResult, 'signature'>>;
     buildExecuteScriptTx(params: SignExecuteScriptTxParams, publicKey: string): Promise<Omit<SignExecuteScriptTxResult, 'signature'>>;
     buildChainedTx(params: SignChainedTxParams[], publicKeys: string[]): Promise<Omit<SignChainedTxResult, 'signature'>[]>;
+    buildGrouplessTransferTx(params: SignGrouplessTransferTxParams): Promise<Omit<SignChainedTxResult, 'signature'>[]>;
+    buildGrouplessDeployContractTx(params: SignGrouplessDeployContractTxParams): Promise<Omit<SignChainedTxResult, 'signature'>[]>;
+    buildGrouplessExecuteScriptTx(params: SignGrouplessExecuteScriptTxParams): Promise<Omit<SignChainedTxResult, 'signature'>[]>;
     static buildUnsignedTx(params: SignUnsignedTxParams): Omit<SignUnsignedTxResult, 'signature'>;
     private buildTransferTxParams;
+    private buildGrouplessTransferTxParams;
+    private buildGrouplessDeployContractTxParams;
+    private buildGrouplessExecuteScriptTxParams;
     private buildDeployContractTxParams;
     private buildExecuteScriptTxParams;
     private convertTransferTxResult;

package/dist/src/signer/tx-builder.js

@@ -109,6 +109,42 @@ class TransactionBuilder {
         });
         return results;
     }
+    async buildGrouplessTransferTx(params) {
+        const data = this.buildGrouplessTransferTxParams(params);
+        const response = await this.nodeProvider.groupless.postGrouplessTransfer(data);
+        return response.map((result) => {
+            return {
+                ...this.convertTransferTxResult(result),
+                type: 'Transfer'
+            };
+        });
+    }
+    async buildGrouplessDeployContractTx(params) {
+        const data = this.buildGrouplessDeployContractTxParams(params);
+        const response = await this.nodeProvider.groupless.postGrouplessDeployContract(data);
+        const transferTxs = response.transferTxs.map((result) => ({
+            ...this.convertTransferTxResult(result),
+            type: 'Transfer'
+        }));
+        const deployContractTx = {
+            ...this.convertDeployContractTxResult(response.deployContractTx),
+            type: 'DeployContract'
+        };
+        return [...transferTxs, deployContractTx];
+    }
+    async buildGrouplessExecuteScriptTx(params) {
+        const data = this.buildGrouplessExecuteScriptTxParams(params);
+        const response = await this.nodeProvider.groupless.postGrouplessExecuteScript(data);
+        const transferTxs = response.transferTxs.map((result) => ({
+            ...this.convertTransferTxResult(result),
+            type: 'Transfer'
+        }));
+        const executeScriptTx = {
+            ...this.convertExecuteScriptTxResult(response.executeScriptTx),
+            type: 'ExecuteScript'
+        };
+        return [...transferTxs, executeScriptTx];
+    }
     static buildUnsignedTx(params) {
         const unsignedTxBin = (0, utils_1.hexToBinUnsafe)(params.unsignedTx);
         const decoded = codec_1.unsignedTxCodec.decode(unsignedTxBin);
@@ -134,6 +170,37 @@ class TransactionBuilder {
             ...rest
         };
     }
+    buildGrouplessTransferTxParams(params) {
+        return {
+            fromAddress: params.fromAddress,
+            destinations: (0, signer_1.toApiDestinations)(params.destinations),
+            gasPrice: (0, api_1.toApiNumber256Optional)(params.gasPrice),
+            targetBlockHash: params.targetBlockHash
+        };
+    }
+    buildGrouplessDeployContractTxParams(params) {
+        return {
+            fromAddress: params.fromAddress,
+            bytecode: params.bytecode,
+            initialAttoAlphAmount: (0, api_1.toApiNumber256Optional)(params.initialAttoAlphAmount),
+            initialTokenAmounts: (0, api_1.toApiTokens)(params.initialTokenAmounts),
+            issueTokenAmount: (0, api_1.toApiNumber256Optional)(params.issueTokenAmount),
+            issueTokenTo: params.issueTokenTo,
+            gasPrice: (0, api_1.toApiNumber256Optional)(params.gasPrice),
+            targetBlockHash: params.targetBlockHash
+        };
+    }
+    buildGrouplessExecuteScriptTxParams(params) {
+        return {
+            fromAddress: params.fromAddress,
+            bytecode: params.bytecode,
+            attoAlphAmount: (0, api_1.toApiNumber256Optional)(params.attoAlphAmount),
+            tokens: (0, api_1.toApiTokens)(params.tokens),
+            gasPrice: (0, api_1.toApiNumber256Optional)(params.gasPrice),
+            targetBlockHash: params.targetBlockHash,
+            gasEstimationMultiplier: params.gasEstimationMultiplier
+        };
+    }
     buildDeployContractTxParams(params, publicKey) {
         TransactionBuilder.validatePublicKey(params, publicKey, params.signerKeyType);
         const { initialAttoAlphAmount, initialTokenAmounts, issueTokenAmount, gasPrice, ...rest } = params;

package/dist/src/signer/types.d.ts

@@ -1,5 +1,6 @@
 import { Number256, Token } from '../api';
 import { node } from '../api';
+import { SimulationResult } from '../api/api-alephium';
 import { NetworkId } from '../utils';
 export type Address = string;
 export type OutputRef = node.OutputRef;
@@ -10,7 +11,7 @@ export interface Destination {
     lockTime?: number;
     message?: string;
 }
-export type KeyType = 'default' | 'bip340-schnorr';
+export type KeyType = 'default' | 'bip340-schnorr' | 'groupless';
 export interface Account {
     keyType: KeyType;
     address: string;
@@ -76,7 +77,7 @@ export interface SignExecuteScriptTxResult {
     signature: string;
     gasAmount: number;
     gasPrice: Number256;
-    simulatedOutputs: node.Output[];
+    simulationResult: SimulationResult;
 }
 export interface SignUnsignedTxParams {
     signerAddress: string;
@@ -112,6 +113,32 @@ export type SignExecuteScriptChainedTxResult = SignExecuteScriptTxResult & {
     type: 'ExecuteScript';
 };
 export type SignChainedTxResult = SignTransferChainedTxResult | SignDeployContractChainedTxResult | SignExecuteScriptChainedTxResult;
+export interface SignGrouplessTransferTxParams {
+    fromAddress: string;
+    destinations: Destination[];
+    gasPrice?: Number256;
+    targetBlockHash?: string;
+}
+export interface SignGrouplessDeployContractTxParams {
+    fromAddress: string;
+    bytecode: string;
+    initialAttoAlphAmount?: Number256;
+    initialTokenAmounts?: Token[];
+    issueTokenAmount?: Number256;
+    issueTokenTo?: string;
+    gasPrice?: Number256;
+    targetBlockHash?: string;
+}
+export interface SignGrouplessExecuteScriptTxParams {
+    fromAddress: string;
+    bytecode: string;
+    attoAlphAmount?: Number256;
+    tokens?: Token[];
+    gasPrice?: Number256;
+    targetBlockHash?: string;
+    gasEstimationMultiplier?: number;
+}
+export type SignGrouplessTxParams = SignGrouplessTransferTxParams | SignGrouplessDeployContractTxParams | SignGrouplessExecuteScriptTxParams;
 export type MessageHasher = 'alephium' | 'sha256' | 'blake2b' | 'identity';
 export interface SignMessageParams {
     signerAddress: string;

package/dist/src/signer/types.js

@@ -28,3 +28,6 @@ utils_1.assertType;
 (0, utils_1.assertType)();
 utils_1.assertType;
 (0, utils_1.assertType)();
+(0, utils_1.assertType)();
+(0, utils_1.assertType)();
+(0, utils_1.assertType)();

package/dist/src/utils/sign.js

@@ -60,7 +60,7 @@ necc.utils.hmacSha256Sync = (key, ...messages) => {
 // hash has to be 32 bytes
 function sign(hash, privateKey, _keyType) {
     const keyType = _keyType ?? 'default';
-    if (keyType === 'default') {
+    if (keyType === 'default' || keyType === 'groupless') {
         const key = ec.keyFromPrivate(privateKey);
         const signature = key.sign(hash);
         return (0, utils_1.encodeSignature)(signature);
@@ -74,7 +74,7 @@ exports.sign = sign;
 function verifySignature(hash, publicKey, signature, _keyType) {
     const keyType = _keyType ?? 'default';
     try {
-        if (keyType === 'default') {
+        if (keyType === 'default' || keyType === 'groupless') {
             const key = ec.keyFromPublic(publicKey, 'hex');
             return key.verify(hash, (0, utils_1.signatureDecode)(ec, signature));
         }

package/dist/src/utils/webcrypto.d.ts

@@ -1,4 +1,6 @@
+/// <reference types="node" />
+import { webcrypto } from 'crypto';
 export declare class WebCrypto {
-    subtle: SubtleCrypto;
+    subtle: webcrypto.SubtleCrypto;
     getRandomValues<T extends ArrayBufferView | null>(array: T): T;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alephium/web3",
-  "version": "1.11.5",
+  "version": "1.12.0-beta.0",
   "description": "A JS/TS library to interact with the Alephium platform",
   "license": "GPL",
   "main": "dist/src/index.js",
@@ -33,7 +33,7 @@
   },
   "author": "Alephium dev <dev@alephium.org>",
   "config": {
-    "alephium_version": "3.10.0",
+    "alephium_version": "3.12.2",
     "explorer_backend_version": "2.3.2"
   },
   "type": "commonjs",
@@ -45,7 +45,7 @@
     "bn.js": "5.2.1",
     "cross-fetch": "^3.1.5",
     "crypto-browserify": "^3.12.0",
-    "elliptic": "6.6.0",
+    "elliptic": "6.6.1",
     "eventemitter3": "^4.0.7",
     "path-browserify": "^1.0.1",
     "stream-browserify": "^3.0.0"

package/src/address/address.ts

@@ -24,10 +24,11 @@ import bs58, { base58ToBytes } from '../utils/bs58'
 import { binToHex, concatBytes, hexToBinUnsafe, isHexString, xorByte } from '../utils'
 import { KeyType } from '../signer'
 import { P2MPKH, lockupScriptCodec } from '../codec/lockup-script-codec'
-import { i32Codec } from '../codec'
+import { i32Codec, intAs4BytesCodec } from '../codec'
 import { LockupScript } from '../codec/lockup-script-codec'
 import djb2 from '../utils/djb2'
 import { TraceableError } from '../error'
+import { byteCodec } from '../codec/codec'
 
 const ec = new EC('secp256k1')
 const PublicKeyHashSize = 32
@@ -36,7 +37,8 @@ export enum AddressType {
   P2PKH = 0x00,
   P2MPKH = 0x01,
   P2SH = 0x02,
-  P2C = 0x03
+  P2C = 0x03,
+  P2PK = 0x04
 }
 
 export function validateAddress(address: string) {
@@ -53,7 +55,7 @@ export function isValidAddress(address: string): boolean {
 }
 
 function decodeAndValidateAddress(address: string): Uint8Array {
-  const decoded = base58ToBytes(address)
+  const decoded = addressToBytes(address)
   if (decoded.length === 0) throw new Error('Address is empty')
   const addressType = decoded[0]
   if (addressType === AddressType.P2MPKH) {
@@ -75,14 +77,77 @@ function decodeAndValidateAddress(address: string): Uint8Array {
   } else if (addressType === AddressType.P2PKH || addressType === AddressType.P2SH || addressType === AddressType.P2C) {
     // [type, ...hash]
     if (decoded.length === 33) return decoded
+  } else if (isGrouplessAddressWithGroup(decoded)) {
+    // [type, keyType, ...publicKey, ...checkSum, ...groupByte]
+    const publicKeyToIndex = decoded.length - 1 - 4
+    const publicKeyLikeBytes = decoded.slice(1, publicKeyToIndex)
+    const checksum = binToHex(decoded.slice(publicKeyToIndex, publicKeyToIndex + 4))
+    const expectedChecksum = binToHex(intAs4BytesCodec.encode(djb2(publicKeyLikeBytes)))
+    if (checksum !== expectedChecksum) {
+      throw new Error(`Invalid checksum for P2PK address: ${address}`)
+    }
+    const group = byteCodec.decode(decoded.slice(decoded.length - 1, decoded.length))
+    validateGroupIndex(group)
+
+    return decoded
   }
 
   throw new Error(`Invalid address: ${address}`)
 }
 
+function isGrouplessAddressWithoutGroup(decoded: Uint8Array): boolean {
+  return decoded[0] === AddressType.P2PK && (decoded.length === 38 || decoded.length === 39)
+}
+
+function isGrouplessAddressWithGroup(decoded: Uint8Array): boolean {
+  return decoded[0] === AddressType.P2PK && (decoded.length === 39 || decoded.length === 40)
+}
+
+export function addressToBytes(address: string): Uint8Array {
+  if (hasExplicitGroupIndex(address)) {
+    const groupIndex = parseGroupIndex(address[address.length - 1])
+    const decoded = base58ToBytes(address.slice(0, address.length - 2))
+    if (isGrouplessAddressWithoutGroup(decoded)) {
+      const groupByte = byteCodec.encode(groupIndex)
+      return new Uint8Array([...decoded, ...groupByte])
+    }
+    throw new Error(`Invalid groupless address: ${address}`)
+  } else {
+    const decoded = base58ToBytes(address)
+    if (isGrouplessAddressWithoutGroup(decoded)) {
+      const group = defaultGroupOfGrouplessAddress(decoded.slice(2, decoded.length - 4))
+      const groupByte = byteCodec.encode(group)
+      return new Uint8Array([...decoded, ...groupByte])
+    }
+    return decoded
+  }
+}
+
 export function isAssetAddress(address: string) {
   const addressType = decodeAndValidateAddress(address)[0]
-  return addressType === AddressType.P2PKH || addressType === AddressType.P2MPKH || addressType === AddressType.P2SH
+  return (
+    addressType === AddressType.P2PKH ||
+    addressType === AddressType.P2MPKH ||
+    addressType === AddressType.P2SH ||
+    addressType === AddressType.P2PK
+  )
+}
+
+export function isGrouplessAddress(address: string) {
+  const addressType = decodeAndValidateAddress(address)[0]
+  return addressType === AddressType.P2PK
+}
+
+export function isGrouplessAddressWithoutGroupIndex(address: string) {
+  return !hasExplicitGroupIndex(address) && isGrouplessAddress(address)
+}
+
+export function isGrouplessAddressWithGroupIndex(address: string) {
+  return hasExplicitGroupIndex(address) && isGrouplessAddress(address)
+}
+
+export function defaultGroupOfGrouplessAddress(pubKey: Uint8Array): number {
+  return pubKey[pubKey.length - 1] & 0xff % TOTAL_NUMBER_OF_GROUPS
 }
 
 export function isContractAddress(address: string) {
@@ -101,6 +166,8 @@ export function groupOfAddress(address: string): number {
     return groupOfP2mpkhAddress(addressBody)
   } else if (addressType == AddressType.P2SH) {
     return groupOfP2shAddress(addressBody)
+  } else if (addressType == AddressType.P2PK) {
+    return groupOfP2pkAddress(addressBody)
   } else {
     // Contract Address
     const id = contractIdFromAddress(address)
@@ -110,17 +177,21 @@ export function groupOfAddress(address: string): number {
 
 // Pay to public key hash address
 function groupOfP2pkhAddress(address: Uint8Array): number {
-  return groupFromBytesForAssetAddress(address)
+  return groupFromBytes(address)
 }
 
 // Pay to multiple public key hash address
 function groupOfP2mpkhAddress(address: Uint8Array): number {
-  return groupFromBytesForAssetAddress(address.slice(1, 33))
+  return groupFromBytes(address.slice(1, 33))
+}
+
+function groupOfP2pkAddress(address: Uint8Array): number {
+  return byteCodec.decode(address.slice(38, 39)) % TOTAL_NUMBER_OF_GROUPS
 }
 
 // Pay to script hash address
 function groupOfP2shAddress(address: Uint8Array): number {
-  return groupFromBytesForAssetAddress(address)
+  return groupFromBytes(address)
 }
 
 export function contractIdFromAddress(address: string): Uint8Array {
@@ -151,7 +222,7 @@ export function groupOfPrivateKey(privateKey: string, keyType?: KeyType): number
 export function publicKeyFromPrivateKey(privateKey: string, _keyType?: KeyType): string {
   const keyType = _keyType ?? 'default'
 
-  if (keyType === 'default') {
+  if (keyType === 'default' || keyType === 'groupless') {
     const key = ec.keyFromPrivate(privateKey)
     return key.getPublic(true, 'hex')
   } else {
@@ -166,6 +237,11 @@ export function addressFromPublicKey(publicKey: string, _keyType?: KeyType): str
     const hash = blake.blake2b(hexToBinUnsafe(publicKey), undefined, 32)
     const bytes = new Uint8Array([AddressType.P2PKH, ...hash])
     return bs58.encode(bytes)
+  } else if (keyType === 'groupless') {
+    const publicKeyBytes = new Uint8Array([0x00, ...hexToBinUnsafe(publicKey)])
+    const hashBytes = intAs4BytesCodec.encode(djb2(publicKeyBytes))
+    const bytes = new Uint8Array([0x04, ...publicKeyBytes, ...hashBytes])
+    return bs58.encode(bytes)
   } else {
     const lockupScript = hexToBinUnsafe(`0101000000000458144020${publicKey}8685`)
     return addressFromScript(lockupScript)
@@ -215,11 +291,13 @@ export function subContractId(parentContractId: string, pathInHex: string, group
 
 export function groupOfLockupScript(lockupScript: LockupScript): number {
   if (lockupScript.kind === 'P2PKH') {
-    return groupFromBytesForAssetAddress(lockupScript.value)
+    return groupFromBytes(lockupScript.value)
   } else if (lockupScript.kind === 'P2MPKH') {
-    return groupFromBytesForAssetAddress(lockupScript.value.publicKeyHashes[0])
+    return groupFromBytes(lockupScript.value.publicKeyHashes[0])
   } else if (lockupScript.kind === 'P2SH') {
-    return groupFromBytesForAssetAddress(lockupScript.value)
+    return groupFromBytes(lockupScript.value)
+  } else if (lockupScript.kind === 'P2PK') {
+    return lockupScript.value.group % TOTAL_NUMBER_OF_GROUPS
   } else {
     // P2C
     const contractId = lockupScript.value
@@ -227,8 +305,38 @@ export function groupOfLockupScript(lockupScript: LockupScript): number {
   }
 }
 
-function groupFromBytesForAssetAddress(bytes: Uint8Array): number {
+export function groupFromBytes(bytes: Uint8Array): number {
   const hint = djb2(bytes) | 1
+  return groupFromHint(hint)
+}
+
+export function groupFromHint(hint: number): number {
   const hash = xorByte(hint)
   return hash % TOTAL_NUMBER_OF_GROUPS
 }
+
+export function hasExplicitGroupIndex(address: string): boolean {
+  return address.length > 2 && address[address.length - 2] === ':'
+}
+
+export function addressFromLockupScript(lockupScript: LockupScript): string {
+  if (lockupScript.kind === 'P2PK') {
+    const groupByte = lockupScriptCodec.encode(lockupScript).slice(-1)
+    const address = bs58.encode(lockupScriptCodec.encode(lockupScript).slice(0, -1))
+    return `${address}:${groupByte}`
+  } else {
+    return bs58.encode(lockupScriptCodec.encode(lockupScript))
+  }
+}
+
+function parseGroupIndex(groupIndexStr: string): number {
+  return validateGroupIndex(parseInt(groupIndexStr), groupIndexStr)
+}
+
+function validateGroupIndex(groupIndex: number, groupIndexStr?: string): number {
+  if (isNaN(groupIndex) || groupIndex < 0 || groupIndex >= TOTAL_NUMBER_OF_GROUPS) {
+    throw new Error(`Invalid group index: ${groupIndexStr ?? groupIndex}`)
+  }
+
+  return groupIndex
+}