Blockchain interface

interface Blockchain {
    create(
        name: string,
        type: BLOCKCHAIN_KEYS,
        exportable: boolean,
        temporary: boolean,
        version?: null | VERSION_OPTIONS,
        seed?: null | string,
        passphrase?: null | string,
    ): Promise<boolean>;
    delete(name: string): Promise<boolean>;
    block(name: string): Promise<boolean>;
    unblock(name: string): Promise<boolean>;
    createBip32ChildKeyDerivation(
        version: VERSION_OPTIONS,
        index: number,
        exportable: boolean,
        temporary: boolean,
        parentKeyName: string,
        childKeyName: string,
    ): Promise<KeyInfo>;
    hashData(
        hashMode: BLOCKCHAIN_HASH_MODE,
        data: Buffer,
    ): Promise<Buffer<ArrayBufferLike>>;
    edDsaSign(
        type: BLOCKCHAIN_EdDSA_TYPE,
        privKeyName: string,
        data: Buffer,
    ): Promise<Buffer<ArrayBufferLike>>;
    getPubKey(
        type: BLOCKCHAIN_GET_PUB_KEY_TYPE,
        privKeyName: string,
    ): Promise<Buffer<ArrayBufferLike>>;
    edDsaVerify(
        type: BLOCKCHAIN_EdDSA_TYPE,
        pubKeyType: BLOCKCHAIN_PUB_KEY_TYPE,
        pubKey: Buffer,
        signature: Buffer,
        data: Buffer,
    ): Promise<boolean>;
    getAddress(
        type: ADDRESS_TYPE,
        version: ADDRESS_VERSION,
        hrp: ADDRESS_HRP,
        pk: string,
    ): Promise<Buffer<ArrayBufferLike>>;
    sign(
        type: BLOCKCHAIN_SIG_TYPE,
        hashMode: BLOCKCHAIN_HASH_MODE,
        hash: Buffer,
        pk: string,
    ): Promise<Buffer<ArrayBufferLike>>;
    getKeyInfo(name: string): Promise<KeyInfo>;
    import(
        format: IMPORT_EXPORT_FORMAT,
        exportable: boolean,
        temporary: boolean,
        name: string,
        data: string,
    ): Promise<boolean>;
    export(
        format: IMPORT_EXPORT_FORMAT,
        version: BLOCKCHAIN_EXPORT_VERSION,
        compressed: boolean,
        name: string,
    ): Promise<Buffer<ArrayBufferLike>>;
    verify(
        sigType: BLOCKCHAIN_SIG_TYPE,
        hashMode: BLOCKCHAIN_HASH_MODE,
        hashData: Buffer,
        signature: Buffer,
        pubKeyType: BLOCKCHAIN_SIG_VERIFY_PUB_KEY_TYPE,
        pubSignature: Buffer,
    ): Promise<boolean>;
    pubKeyRecovery(
        sigType: BLOCKCHAIN_SIG_TYPE,
        hashMode: BLOCKCHAIN_HASH_MODE,
        hashData: Buffer,
        signature: Buffer,
    ): Promise<Buffer<ArrayBufferLike>>;
    abn128RndCtxGetPt(
        x: string | Buffer<ArrayBufferLike>,
        y: string | Buffer<ArrayBufferLike>,
    ): Promise<Buffer<ArrayBufferLike>>;
    abn128RndCtxMultAdd(
        keyName: string,
        scalar: string | Buffer<ArrayBufferLike>,
    ): Promise<Buffer<ArrayBufferLike>>;
    abn128RndScs(): Promise<Buffer<ArrayBufferLike>[]>;
    abn128RndSc(): Promise<Buffer<ArrayBufferLike>>;
    abn128RndCtxRefresh(
        x: string | Buffer<ArrayBufferLike>,
        y: string | Buffer<ArrayBufferLike>,
    ): Promise<Buffer<ArrayBufferLike>>;
    abn128PscMult(
        keyName: string,
        x: string | Buffer<ArrayBufferLike>,
        y: string | Buffer<ArrayBufferLike>,
        neg?: boolean,
    ): Promise<Buffer<ArrayBufferLike>>;
}

Methods

create

create(
    name: string,
    type: BLOCKCHAIN_KEYS,
    exportable: boolean,
    temporary: boolean,
    version?: null | VERSION_OPTIONS,
    seed?: null | string,
    passphrase?: null | string,
): Promise<boolean>
Creates an Extended Private Key (XPrv) for the blockchain in the BIP32 standard.
Parameters
- name: string
  Name of the key in the HSM.
- type: BLOCKCHAIN_KEYS
  Type of key generation.
- exportable: boolean
  If the key is exportable.
- temporary: boolean
  If the key is temporary.
- Optionalversion: null | VERSION_OPTIONS
  Key version that must be passed according to the type option
- Optionalseed: null | string
  Buffer containing the data needed to generate the key. The input data must be passed according to the enums.BLOCKCHAIN_KEYS type option.
- Optionalpassphrase: null | string
Returns Promise<boolean>
Key created.

Throws
exceptions.HsmError If it is not possible to create the key or there is an error in the operation.

See
Example code: Creating a blockchain key

delete

delete(name: string): Promise<boolean>
Deletes a key stored in the HSM.
Parameters
- name: string
  Key name.
Returns Promise<boolean>
Returns true if the key was successfully deleted.

Throws
If the key name is invalid.

Throws
In the event of an error when deleting the key.

See
Example code: Deleting a blockchain key

block

block(name: string): Promise<boolean>
Locks a key in the HSM.
Parameters
- name: string
  Key name.
Returns Promise<boolean>
Returns true if the key was successfully locked.

Throws
If the key name is invalid.

Throws
In the event of an error when deleting the key.

See
Example code: Locking a blockchain key

unblock

unblock(name: string): Promise<boolean>
Unlocks a key in the HSM.
Parameters
- name: string
  Key name.
Returns Promise<boolean>
Returns true if the key was successfully unlocked.

Throws
If the key name is invalid.

Throws
In the event of an error when deleting the key.

See
Example code: Unlocking a blockchain key

createBip32ChildKeyDerivation

createBip32ChildKeyDerivation(
    version: VERSION_OPTIONS,
    index: number,
    exportable: boolean,
    temporary: boolean,
    parentKeyName: string,
    childKeyName: string,
): Promise<KeyInfo>
Performs a Child Key Derivation (CKD) operation. Derives an Extended Private Key (XPrv) for the blockchain in the BIP32 standard.
Parameters
- version: VERSION_OPTIONS
  Key version.
- index: number
  Index of the key to be derived. Non-hardened keys use an index from 0 to^231-1 and hardened (unrestrictedly secure) keys use indexes from²³¹ to^232-1, as specified in the BIP32 standard. It is highly recommended to generate hardened keys.
- exportable: boolean
  If the key is exportable.
- temporary: boolean
  If the key is temporary.
- parentKeyName: string
  Name of the parent key in the HSM. It must be an XPrv key.
- childKeyName: string
  Name of the key that will be derived in the HSM.
Returns Promise<KeyInfo>
Information on the derived key.

Throws
exceptions.HsmError If it is not possible to derive the key or an error occurs in the operation.

See
Example code: Creating a derived bip32 blockchain key

hashDate

hashData(
hashMode: BLOCKCHAIN_HASH_MODE,
date: Buffer,
): Promise<Buffer<ArrayBufferLike>>
Calculates a hash using the blockchain module.
Parameters
- hashMode: BLOCKCHAIN_HASH_MODE
  Hash mode.
- date: Buffer
  Data to be processed. Maximum size of constants.BLOCKCHAIN_MAX_DATA_LEN.
Returns Promise<Buffer<ArrayBufferLike>>
Calculated hash.

Throws
exceptions.HsmError If the hash cannot be calculated or an error occurs in the operation.

See
Example code: Generating data hash

edDsaSign

edDsaSign(
    type: BLOCKCHAIN_EdDSA_TYPE,
    privKeyName: string,
    date: Buffer,
): Promise<Buffer<ArrayBufferLike>>
Generates an EdDSA signature using the blockchain module.
Parameters
- type: BLOCKCHAIN_EdDSA_TYPE
  Type of signature to be generated.
- privKeyName: string
  Name of the private key.
- date: Buffer
  Data that will be signed.
Returns Promise<Buffer<ArrayBufferLike>>
Signature generated.

Throws
exceptions.HsmError If it is not possible to sign the data or an error occurs in the operation.

See
Example code: Signing hash with EdDSA blockchain key

getPubKey

getPubKey(
type: BLOCKCHAIN_GET_PUB_KEY_TYPE,
privKeyName: string,
): Promise<Buffer<ArrayBufferLike>>
Recover a public key from a private key using the blockchain module.
Parameters
- type: BLOCKCHAIN_GET_PUB_KEY_TYPE
  Format of the public key to be exported.
- privKeyName: string
  Name of the private key.
Returns Promise<Buffer<ArrayBufferLike>>
Public key.

Throws
exceptions.HsmError If the private key is not found or there is an error in the operation.

See
Example code: Retrieving a blockchain public key

edDsaVerify

edDsaVerify(
    type: BLOCKCHAIN_EdDSA_TYPE,
    pubKeyType: BLOCKCHAIN_PUB_KEY_TYPE,
    pubKey: Buffer,
    signature: Buffer,
    date: Buffer,
): Promise<boolean>
Verifies an EdDSA signature using the blockchain module.
Parameters
- type: BLOCKCHAIN_EdDSA_TYPE
  Type of signature to be verified.
- pubKeyType: BLOCKCHAIN_PUB_KEY_TYPE
  Type of public key.
- pubKey: Buffer
  Public key. This must be a valid public key returned by the Blockchain.getPubKey method.
- signature: Buffer
  Signature to be verified. Must be a valid signature returned by the Blockchain.edDsaSign method.
- date: Buffer
  Data that has been signed. It must be a valid hash returned by the Blockchain.hashData method.
Returns Promise<boolean>
True if the signature is valid, false otherwise.

Throws
exceptions.HsmError If an error occurs in the operation.

See
Example code: Verifying hash signatures with EdDSA blockchain

getAddress

getAddress(
    type: ADDRESS_TYPE,
    version: ADDRESS_VERSION,
    hrp: ADDRESS_HRP,
    pk: string,
): Promise<Buffer<ArrayBufferLike>>
Retrieves the address of a key using the blockchain module.
Parameters
- type: ADDRESS_TYPE
  Type of address to be generated.
- version: ADDRESS_VERSION
  Address version.
- hrp: ADDRESS_HRP
  HRP (Human Readable Part) of the key.
- pk: string
  Private key from which the address or script-hash will be generated.
Returns Promise<Buffer<ArrayBufferLike>>
Returns the address.

Throws
exceptions.HsmError If the address cannot be retrieved or an error occurs in the operation.

See
Example code: Getting the blockchain address from the private key

ATTENTION
P2TR addresses (without key tweak) should only be used with BIP340/Schnorr signatures in single-key-setting scenarios.

sign

sign(
    type: BLOCKCHAIN_SIG_TYPE,
    hashMode: BLOCKCHAIN_HASH_MODE,
    hash: Buffer,
    pk: string,
): Promise<Buffer<ArrayBufferLike>>
Sign a hash using the blockchain module.
Parameters
- type: BLOCKCHAIN_SIG_TYPE
  Type of signature to be made.
- hashMode: BLOCKCHAIN_HASH_MODE
  Hash mode.
- hash: Buffer
  Hash calculated according to what is entered in hashMode(enums.BLOCKCHAIN_HASH_MODE).
- pk: string
  Name of the private key.
Returns Promise<Buffer<ArrayBufferLike>>
Throws
exceptions.HsmError If it is not possible to sign the data or an error occurs in the operation.

See
Example code: Signing hash with ECDSA blockchain key

getKeyInfo

getKeyInfo(name: string): Promise<KeyInfo>
Retrieves the properties of a key using the blockchain module.
Parameters
- name: string
  Name of the private key.
Returns Promise<KeyInfo>
Returns an object with the key's blockchain data.

Throws
exceptions.HsmError If the address cannot be retrieved or an error occurs in the operation.

See
Sample code: Getting information from a blockchain key

import

import(
    format: IMPORT_EXPORT_FORMAT,
    exportable: boolean,
    temporary: boolean,
    name: string,
    date: string,
): Promise<boolean>
Import a private key using the blockchain_interfaces module.
Parameters
- format: IMPORT_EXPORT_FORMAT
  Format of the key to be imported.
- exportable: boolean
  If the key is exportable.
- temporary: boolean
  If the key is temporary.
- name: string
  Name of the private key.
- date: string
  Private key in the format specified in enums.IMPORT_EXPORT_FORMAT.
Returns Promise<boolean>
True if the import was carried out or an exception otherwise.

Throws
exceptions.HsmError If an error occurs in the operation.

See
Example code: Importing a blockchain private key

export

export(
    format: IMPORT_EXPORT_FORMAT,
    version: BLOCKCHAIN_EXPORT_VERSION,
    compressed: boolean,
    name: string,
): Promise<Buffer<ArrayBufferLike>>
Export a private key using the blockchain module.
Parameters
- format: IMPORT_EXPORT_FORMAT
  Format of the key to be exported.
- version: BLOCKCHAIN_EXPORT_VERSION
  Key version.
- compressed: boolean
  If the key is to be returned compressed.
- name: string
  Name of the private key.
Returns Promise<Buffer<ArrayBufferLike>>
Buffer with the private key.

Throws
exceptions.HsmError If an error occurs in the operation.

See
Sample code: Exporting a blockchain private key

check

check(
    sigType: BLOCKCHAIN_SIG_TYPE,
    hashMode: BLOCKCHAIN_HASH_MODE,
    hashData: Buffer,
    signature: Buffer,
    pubKeyType: BLOCKCHAIN_SIG_VERIFY_PUB_KEY_TYPE,
    pubSignature: Buffer,
): Promise<boolean>
Verifies a signature using the blockchain module.
Parameters
- sigType: BLOCKCHAIN_SIG_TYPE
  Type of signature made.
- hashMode: BLOCKCHAIN_HASH_MODE
  Hash mode.
- hashData: Buffer
  Hash calculated as entered in hashData.
- signature: Buffer
  Signature as informed in sigType(enums.BLOCKCHAIN_SIG_TYPE).
- pubKeyType: BLOCKCHAIN_SIG_VERIFY_PUB_KEY_TYPE
  Type of public key.
- pubSignature: Buffer
  Public key as entered in pubKeyType.
Returns Promise<boolean>
True if the signature is valid, false otherwise.

Throws
exceptions.HsmError If an error occurs in the operation.

See
Example code: Verifying ECDSA blockchain signature

pubKeyRecovery

pubKeyRecovery(
    sigType: BLOCKCHAIN_SIG_TYPE,
    hashMode: BLOCKCHAIN_HASH_MODE,
    hashData: Buffer,
    signature: Buffer,
): Promise<Buffer<ArrayBufferLike>>
Retrieves a public key (PBK) from an ECDSA-type signature.
Parameters
- sigType: BLOCKCHAIN_SIG_TYPE
  Type of signature to be generated.
- hashMode: BLOCKCHAIN_HASH_MODE
  Hash mode.
- hashData: Buffer
  Hash calculated as entered in hashData.
- signature: Buffer
  Signature as informed in sigType(enums.BLOCKCHAIN_SIG_TYPE).
Returns Promise<Buffer<ArrayBufferLike>>
Returns a buffer with the public key.

Throws
exceptions.HsmError If an error occurs in the operation.

See
Sample code: Retrieving public key from signature

abn128RndCtxGetPt

abn128RndCtxGetPt(
x: string | Buffer<ArrayBufferLike>,
y: string | Buffer<ArrayBufferLike>,
): Promise<Buffer<ArrayBufferLike>>
Calculates a point from another point and a random context.
Parameters
- x: string | Buffer<ArrayBufferLike>
  Point X which can be a buffer of constants.ABN128_XY_BUFF_LEN bytes or a hexadecimal string of constants.ABN128_XY_HEX_LEN characters.
- y: string | Buffer<ArrayBufferLike>
  Y point which can be a buffer of constants.ABN128_XY_BUFF_LEN bytes or a hexadecimal string of constants.ABN128_XY_HEX_LEN characters.
Returns Promise<Buffer<ArrayBufferLike>>
Returns a buffer with the calculated point.

Throws
If any of the parameters entered are invalid.

Throws
exceptions.InvalidParameterError If any parameter entered is invalid.

Throws
exceptions.HsmError If an error occurs in the operation.

abn128RndCtxMultAdd

abn128RndCtxMultAdd(
keyName: string,
scalar: string | Buffer<ArrayBufferLike>,
): Promise<Buffer<ArrayBufferLike>>
Multiplies a scalar by the private key and adds a random scalar.
Parameters
- keyName: string
  Name of the key that will be used for the operation.
- scalar: string | Buffer<ArrayBufferLike>
  Scalar that can be a buffer of constants.ABN128_XY_BUFF_LEN bytes or a hexadecimal string of constants.ABN128_XY_HEX_LEN characters.
Returns Promise<Buffer<ArrayBufferLike>>
Returns a buffer with the result of the operation.

Throws
If the key name is invalid.

Throws
exceptions.InvalidParameterError If any parameter entered is invalid.

Throws
exceptions.HsmError If an error occurs in the operation.

abn128RndScs

abn128RndScs(): Promise<Buffer<ArrayBufferLike>[]>
Returns four random scalars.

Returns Promise<Buffer<ArrayBufferLike>[]>
Returns an array of buffers with random scalars.

Throws
exceptions.HsmError If an error occurs in the operation.

abn128RndSc

abn128RndSc(): Promise<Buffer<ArrayBufferLike>>
Returns a random scalar.

Returns Promise<Buffer<ArrayBufferLike>>
Returns a buffer with the random scalar.

Throws
exceptions.HsmError If an error occurs in the operation.

abn128RndCtxRefresh

abn128RndCtxRefresh(
x: string | Buffer<ArrayBufferLike>,
y: string | Buffer<ArrayBufferLike>,
): Promise<Buffer<ArrayBufferLike>>
Updates the random context.
Parameters
- x: string | Buffer<ArrayBufferLike>
  Point X which can be a buffer of constants.ABN128_XY_BUFF_LEN bytes or a hexadecimal string of constants.ABN128_XY_HEX_LEN characters.
- y: string | Buffer<ArrayBufferLike>
  Y point which can be a buffer of constants.ABN128_XY_BUFF_LEN bytes or a hexadecimal string of constants.ABN128_XY_HEX_LEN characters.
Returns Promise<Buffer<ArrayBufferLike>>
Returns a buffer with the calculated point.

Throws
If any of the parameters entered are invalid.

Throws
exceptions.InvalidParameterError If any parameter entered is invalid.

Throws
exceptions.HsmError If an error occurs in the operation.

abn128PscMult

abn128PscMult(
    keyName: string,
    x: string | Buffer<ArrayBufferLike>,
    y: string | Buffer<ArrayBufferLike>,
    neg?: boolean,
): Promise<Buffer<ArrayBufferLike>>
Multiplies a scalar by the private key.
Parameters
- keyName: string
  Name of the key that will be used for the operation.
- x: string | Buffer<ArrayBufferLike>
  Point X which can be a buffer of constants.ABN128_XY_BUFF_LEN bytes or a hexadecimal string of constants.ABN128_XY_HEX_LEN characters.
- y: string | Buffer<ArrayBufferLike>
  Y point which can be a buffer of constants.ABN128_XY_BUFF_LEN bytes or a hexadecimal string of constants.ABN128_XY_HEX_LEN characters.
- Optionalneg: boolean
  Whether the private key should be negated.
Returns Promise<Buffer<ArrayBufferLike>>
Returns a buffer with the calculated point.

Throws
If any of the parameters entered are invalid.

Throws
exceptions.InvalidParameterError If any parameter entered is invalid.

Throws
exceptions.HsmError If an error occurs in the operation.

Blockchain interface

Index

Methods

Methods

create

Parameters

Returns Promise<boolean>

Throws

See

delete

Parameters

Returns Promise<boolean>

Throws

Throws

See

block

Parameters

Returns Promise<boolean>

Throws

Throws

See

unblock

Parameters

Returns Promise<boolean>

Throws

Throws

See

createBip32ChildKeyDerivation

Parameters

Returns Promise<KeyInfo>

Throws

See

hashDate

Parameters

Returns Promise<Buffer<ArrayBufferLike>>

Throws

See

edDsaSign

Parameters

Returns Promise<Buffer<ArrayBufferLike>>

Throws

See

getPubKey

Parameters

Returns Promise<Buffer<ArrayBufferLike>>

Throws

See

edDsaVerify

Parameters

Returns Promise<boolean>

Throws

See

getAddress

Parameters

Returns Promise<Buffer<ArrayBufferLike>>

Throws

See

ATTENTION

sign

Parameters

Returns Promise<Buffer<ArrayBufferLike>>

Throws

See

getKeyInfo

Parameters

Returns Promise<KeyInfo>

Throws

See

import

Parameters

Returns Promise<boolean>

Throws

See

export

Parameters

Returns Promise<Buffer<ArrayBufferLike>>

Throws

See

check

Parameters