@bitgo-beta/sdk-coin-flrp 1.0.1-beta.4 → 1.0.1-beta.400

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

@@ -1,157 +1,193 @@
-import { TransferableOutput } from '@flarenetwork/flarejs';
+import { Signature, TransferableOutput, Id, Utxo } from '@flarenetwork/flarejs';
 import { BaseUtils, Entry } from '@bitgo-beta/sdk-core';
 import { FlareNetwork } from '@bitgo-beta/statics';
-import { DeprecatedOutput, DeprecatedTx, Output } from './iface';
+import { Buffer } from 'buffer';
+import { DecodedUtxoObj, Output, Tx } from './iface';
 export declare class Utils implements BaseUtils {
+    isValidTransactionId(txId: string): boolean;
+    isValidSignature(signature: string): boolean;
+    /**
+     * Check if addresses in wallet match UTXO output addresses
+     */
     includeIn(walletAddresses: string[], otxoOutputAddresses: string[]): boolean;
     /**
-     * Checks if it is a valid address no illegal characters
-     *
-     * @param {string} address - address to be validated
-     * @returns {boolean} - the validation result
+     * Validates a Flare address or array of addresses
+     * @param {string | string[]} address - address(es) to validate
+     * @returns {boolean} - validation result
      */
-    /** @inheritdoc */
     isValidAddress(address: string | string[]): boolean;
     private isValidAddressRegex;
     /**
-     * Checks if it is a valid blockId with length 66 including 0x
-     *
-     * @param {string} hash - blockId to be validated
-     * @returns {boolean} - the validation result
+     * Validates a block ID
+     * @param {string} hash - block ID to validate
+     * @returns {boolean} - validation result
      */
-    /** @inheritdoc */
     isValidBlockId(hash: string): boolean;
     /**
-     * Checks if the string is a valid protocol public key or
-     * extended public key.
-     *
-     * @param {string} pub - the  public key to be validated
-     * @returns {boolean} - the validation result
+     * Validates a public key
+     * @param {string} pub - public key to validate
+     * @returns {boolean} - validation result
      */
     isValidPublicKey(pub: string): boolean;
-    parseAddress: (pub: string) => Buffer;
     /**
-     * Returns whether or not the string is a valid protocol private key, or extended
-     * private key.
-     *
-     * The protocol key format is described in the @stacks/transactions npm package, in the
-     * createStacksPrivateKey function:
-     * https://github.com/blockstack/stacks.js/blob/master/packages/transactions/src/keys.ts#L125
-     *
-     * @param {string} prv - the private key (or extended private key) to be validated
-     * @returns {boolean} - the validation result
+     * Validates a private key
+     * @param {string} prv - private key to validate
+     * @returns {boolean} - validation result
      */
     isValidPrivateKey(prv: string): boolean;
     /**
-     * Returns whether or not the string is a composed of hex chars only
-     *
-     * @param {string} maybe - the  string to be validated
-     * @returns {boolean} - the validation result
+     * Checks if a string contains only hex characters
      */
-    allHexChars(maybe: string): boolean;
-    /** @inheritdoc */
-    isValidSignature(signature: string): boolean;
-    /** @inheritdoc */
-    isValidTransactionId(txId: string): boolean;
+    allHexChars(str: string): boolean;
     /**
-     * FlareJS wrapper to create signature and return it for credentials
-     * @param network
-     * @param message
-     * @param prv
-     * @return signature
+     * Creates a signature using the Flare network parameters
+     * Returns a 65-byte signature (64 bytes signature + 1 byte recovery parameter)
      */
     createSignature(network: FlareNetwork, message: Buffer, prv: Buffer): Buffer;
     /**
-     * FlareJS wrapper to verify signature
-     * @param network
-     * @param message
-     * @param signature
-     * @param publicKey - public key instead of private key for verification
-     * @return true if it's verify successful
+     * Verifies a signature
+     * @param messageHash - The SHA256 hash of the message (e.g., signablePayload)
+     * @param signature - The 64-byte signature (without recovery parameter)
+     * @param publicKey - The public key to verify against
+     * @returns true if signature is valid
      */
-    verifySignature(network: FlareNetwork, message: Buffer, signature: Buffer, publicKey: Buffer): boolean;
+    verifySignature(messageHash: Buffer, signature: Buffer, publicKey: Buffer): boolean;
     /**
-     * FlareJS wrapper to recover signature
-     * @param network
-     * @param message
-     * @param signature
-     * @return recovered public key
+     * Creates a new signature object
      */
-    recoverySignature(network: FlareNetwork, message: Buffer, signature: Buffer): Buffer;
-    sha256(buf: Uint8Array): Buffer;
+    createNewSig(sigHex: string): Signature;
     /**
-     * Check the raw transaction has a valid format in the blockchain context, throw otherwise.
-     * It's to reuse in TransactionBuilder and TransactionBuilderFactory
-     *
-     * @param rawTransaction Transaction as hex string
+     * Creates an empty signature with embedded address for signature slot identification.
+     * The address is embedded at position 90 (after the first 45 zero bytes).
+     * This allows the signing logic to determine which slot belongs to which address.
+     * @param addressHex The 20-byte address in hex format (40 chars, without 0x prefix)
      */
-    validateRawTransaction(rawTransaction: string): void;
+    createEmptySigWithAddress(addressHex: string): Signature;
     /**
-     * Check if tx is for the blockchainId
-     *
-     * @param {DeprecatedTx} tx
-     * @param {string} blockchainId
-     * @returns true if tx is for blockchainId
+     * Extracts the embedded address from an empty signature.
+     * Returns the address hex string (40 chars) or empty string if not found.
      */
-    isTransactionOf(tx: DeprecatedTx, blockchainId: string): boolean;
+    getAddressFromEmptySig(sig: string): string;
     /**
-     * Check if Output is from PVM.
-     * Output could be EVM or PVM output.
-     * @param {DeprecatedOutput} output
-     * @returns {boolean} output has transferable output structure
+     * Computes SHA256 hash
      */
-    deprecatedIsTransferableOutput(output: DeprecatedOutput): boolean;
+    sha256(buf: Uint8Array): Buffer;
     /**
-     * Check if Output is from PVM.
-     * Output could be EVM or PVM output.
-     * @param {Output} output
-     * @returns {boolean} output is TransferableOutput
+     * Validates raw transaction format
      */
-    isTransferableOutput(output: Output): output is TransferableOutput;
+    validateRawTransaction(rawTransaction: string): void;
     /**
-     * Return a mapper function to that network address representation.
-     * @param network required to stringify addresses
-     * @return mapper function
+     * Checks if output is TransferableOutput type
      */
-    deprecatedMapOutputToEntry(network: FlareNetwork): (output: DeprecatedOutput) => Entry;
+    isTransferableOutput(output: Output): output is TransferableOutput;
     /**
-     * Return a mapper function to that network address representation.
-     * @param network required to stringify addresses
-     * @return mapper function
+     * Maps outputs to entry format
      */
     mapOutputToEntry(network: FlareNetwork): (Output: any) => Entry;
     /**
-     * remove hex prefix (0x)
-     * @param hex string
-     * @returns hex without 0x
+     * Removes 0x prefix from hex string
      */
     removeHexPrefix(hex: string): string;
     /**
-     * Outputidx convert from number (as string) to buffer.
-     * @param {string} outputidx number
-     * @return {Buffer} buffer of size 4 with that number value
+     * Converts output index to buffer
      */
     outputidxNumberToBuffer(outputidx: string): Buffer;
     /**
-     * Outputidx buffer to number (as string)
-     * @param {Buffer} outputidx
-     * @return {string} outputidx number
+     * Converts output index buffer to number string
      */
     outputidxBufferToNumber(outputidx: Buffer): string;
     /**
-     * CB58 decode function - simple Base58 decode implementation
-     * @param {string} data - CB58 encoded string
-     * @returns {Buffer} decoded buffer
+     * Helper method to convert address components to string
+     */
+    addressToString: (hrp: string, prefix: string, address: Buffer) => string;
+    /**
+     * Decodes a base58 string with checksum to a Buffer
+     */
+    cb58Decode(str: string): Buffer;
+    /**
+     * Validates a checksum on a Buffer and returns true if valid, false if not
+     */
+    private validateChecksum;
+    /**
+     * Encodes a Buffer as a base58 string with checksum
+     */
+    cb58Encode(bytes: Buffer): string;
+    /**
+     * Adds a checksum to a Buffer and returns the concatenated result
+     * Uses last 4 bytes of SHA256 hash as checksum (matching avaxp behavior)
+     */
+    addChecksum(buff: Buffer | Uint8Array): Uint8Array;
+    /**
+     * Parse an address string into a Buffer
+     * @param address - The address to parse
+     * @returns Buffer containing the parsed address
+     */
+    parseAddress: (address: string) => Buffer;
+    stringToAddress: (address: string, hrp?: string) => Buffer;
+    flareIdString(value: string): Id;
+    /**
+     * Sort addresses lexicographically by their byte representation.
+     * This matches how addresses are stored on-chain in Avalanche/Flare P-chain UTXOs.
+     * @param addresses - Array of bech32 address strings (e.g., "P-costwo1...")
+     * @returns Array of addresses sorted by hex value
+     */
+    sortAddressesByHex(addresses: string[]): string[];
+    /**
+     * Sort address buffers lexicographically by their byte representation.
+     * This matches how addresses are stored on-chain in Avalanche/Flare P-chain UTXOs.
+     * @param addressBuffers - Array of address byte buffers
+     * @returns Array of address buffers sorted by hex value
+     */
+    sortAddressBuffersByHex(addressBuffers: Buffer[]): Buffer[];
+    /**
+     * Recover public key from signature
+     * @param messageHash - The SHA256 hash of the message (e.g., signablePayload)
+     * @param signature - 65-byte signature (64 bytes signature + 1 byte recovery parameter)
+     * @return recovered public key
+     */
+    recoverySignature(messageHash: Buffer, signature: Buffer): Buffer;
+    /**
+     * Check if tx is for the blockchainId
+     *
+     * @param {Tx} tx
+     * @param {string} blockchainId - blockchain ID in hex format
+     * @returns true if tx is for blockchainId
+     */
+    isTransactionOf(tx: Tx, blockchainId: string): boolean;
+    /**
+     * Convert FlareJS native Utxo to DecodedUtxoObj for internal use
+     * @param utxo - FlareJS Utxo object
+     * @param network - Flare network configuration
+     * @returns DecodedUtxoObj compatible with existing methods
+     */
+    utxoToDecoded(utxo: Utxo, network: FlareNetwork): DecodedUtxoObj;
+    /**
+     * Convert array of FlareJS Utxos to DecodedUtxoObj array
+     * @param utxos - Array of FlareJS Utxo objects
+     * @param network - Flare network configuration
+     * @returns Array of DecodedUtxoObj
+     */
+    utxosToDecoded(utxos: Utxo[], network: FlareNetwork): DecodedUtxoObj[];
+    /**
+     * Convert DecodedUtxoObj to native FlareJS Utxo object
+     * This is the reverse of utxoToDecoded
+     *
+     * IMPORTANT: Addresses are sorted lexicographically by byte value to match
+     * on-chain storage order. The API may return addresses in arbitrary order, but
+     * on-chain UTXOs always store addresses in sorted order.
+     *
+     * @param decoded - DecodedUtxoObj to convert
+     * @param assetId - Asset ID as cb58 encoded string
+     * @returns Native FlareJS Utxo object
      */
-    cb58Decode(data: string): Buffer;
+    decodedToUtxo(decoded: DecodedUtxoObj, assetId: string): Utxo;
     /**
-     * Convert address buffer to bech32 string
-     * @param {string} hrp - Human readable part
-     * @param {string} chainid - Chain identifier
-     * @param {Buffer} addressBuffer - Address buffer
-     * @returns {string} Address string
+     * Convert array of DecodedUtxoObj to native FlareJS Utxo objects
+     * @param decodedUtxos - Array of DecodedUtxoObj
+     * @param assetId - Asset ID as cb58 encoded string
+     * @returns Array of native FlareJS Utxo objects
      */
-    addressToString(hrp: string, chainid: string, addressBuffer: Buffer): string;
+    decodedToUtxos(decodedUtxos: DecodedUtxoObj[], assetId: string): Utxo[];
 }
 declare const utils: Utils;
 export default utils;

package/dist/src/lib/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/lib/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EACL,SAAS,EACT,KAAK,EAMN,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAcjE,qBAAa,KAAM,YAAW,SAAS;IAC9B,SAAS,CAAC,eAAe,EAAE,MAAM,EAAE,EAAE,mBAAmB,EAAE,MAAM,EAAE,GAAG,OAAO;IAInF;;;;;OAKG;IACH,kBAAkB;IAClB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO;IAYnD,OAAO,CAAC,mBAAmB;IAI3B;;;;;OAKG;IACH,kBAAkB;IAClB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAUrC;;;;;;OAMG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAwC/B,YAAY,QAAS,MAAM,KAAG,MAAM,CAGzC;IAEF;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAiBvC;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAInC,kBAAkB;IAClB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI5C,kBAAkB;IAClB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI3C;;;;;;OAMG;IACH,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAU5E;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAQtG;;;;;;OAMG;IACH,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAUpF,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM;IAI/B;;;;;OAKG;IACH,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IASpD;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO;IAahE;;;;;OAKG;IACH,8BAA8B,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;IAIjE;;;;;OAKG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,kBAAkB;IAIlE;;;;OAIG;IACH,0BAA0B,CAAC,OAAO,EAAE,YAAY,GAAG,CAAC,MAAM,EAAE,gBAAgB,KAAK,KAAK;IA4BtF;;;;OAIG;IACH,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,CAAC,MAAM,KAAA,KAAK,KAAK;IAmB1D;;;;OAIG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAOpC;;;;OAIG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIlD;;;;OAIG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIlD;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAWhC;;;;;;OAMG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;CAI7E;AAED,QAAA,MAAM,KAAK,OAAc,CAAC;AAE1B,eAAe,KAAK,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/lib/utils.ts"],"names":[],"mappings":"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"}