Detailed description

Operations to support the security of Blockchain-based structures.

The Blockchain module APIs are aimed at specific operations for processing blockchain network cryptography and BIP, EIP and SLIP specifications.

The ECDSA signature, for example, is specialized to avoid signature malleabilitywith the restriction of LOW-S.

Examples of operations available in the Blockchain module:

Extended Private Key (XPrv) generation in the BIP32 standard.

Child Key Derivation in the BIP32 and SLIP10 standards.

Address recovery.

ECDSA digital signatures, in SECG strict DER standards (BIP62/66 and BIP 146) and Schnorr in BIP340 standard;

Digital signatures EdDSA curve 25519.

Signature verification.

Import and export of keys via various formats (WIF, Hex, Sec1, Xpriv etc).

Recovery of the public key with different formats (BIP32 Xpub, Sec1 with and without compression, Schnorr BIP340 etc).

Split and Recover secrets with M from N scheme using SSS (Shamir's Secret Sharing).

Operations with the curve alt_bn128according to EIP-196.

Attention: The blockchain module does not handle or assemble the transaction details for each particular network; this must be left to the application. The function of the HSM is to protect the private key in a secure environment, generate and return a signature according to the parameters passed by the calling application.

Compatible networks

Below is the list of networks whose encryption is compatible with HSM:

Observation: The algorithms listed are those currently implemented in the HSM that allow transactions to be signed on the network and do not necessarily cover all the options defined in the network specification. If you have any questions, feel free to contact Dinamo Networks support and ask them.

Name	Symbol	Alg. Signature in HSM	Curve	Obs
Bitcoin	BTC	ECDSA	secp256k1
Ethereum	ETH	ECDSA	secp256k1
Tether	USDT	ECDSA	secp256k1	token on various networks (e.g. Ethereum, Algorand)
Binance Coin	BNB	ECDSA	secp256k1
USD Coin	USDC	ECDSA	secp256k1	token
Solana	SUN	EdDSA	edwards25519
XRP	XRP	ECDSA, EdDSA	secp256k1, edwards25519
Terra Classic	LUNC	ECDSA	secp256k1
Cardano	ADA	EdDSA	edwards25519
Avalanche	AVAX	ECDSA	secp256k1
Dogecoin	DOGE	ECDSA	secp256k1
Binance USD	BUSD	ECDSA	secp256k1	token
Polkadot	DOT	ECDSA, EdDSA	secp256k1, edwards25519
Shiba Inu	SHIB	ECDSA	secp256k1	token
Wrapped Bitcoin	WBTC	ECDSA, EdDSA	secp256k1, edwards25519	token
Polygon	MATIC	ECDSA	secp256k1
Cronos	CRO	ECDSA	secp256k1
Dai	DAI	ECDSA	secp256k1	token
NEAR Protocol	NEAR	ECDSA	secp256k1
Litecoin	LTC	ECDSA	secp256k1
TRON	TRX	ECDSA	secp256k1
ApeCoin	EPA	ECDSA	secp256k1	token
Cosmos	ATOM	ECDSA	secp256k1
Bitcoin Cash	BCH	ECDSA	secp256k1
Algorand	SOMETHING	EdDSA	edwards25519
Brazilian Digital Token	BRZ	ECDSA	secp256k1	token
Celo Brazilian Real	CREAL	ECDSA	secp256k1	token
Celo Dollar	CUSD	ECDSA	secp256k1	token
Axie Infinity	AXS	ECDSA	secp256k1	token/coin
Fantom	FTM	ECDSA	secp256k1
Uniswap	UNI	ECDSA	secp256k1	token
Stellar	XLM	EdDSA	edwards25519
Tezos	XTZ	ECDSA, EdDSA	secp256k1, edwards25519
CELO	CELO	ECDSA	secp256k1	token/coin
Toncoin	TON	EdDSA	edwards25519
Chainlink	LINK	ECDSA	secp256k1	token

The HSM implementation complies with the standards defined in the documentation listed below:

BIP32 - Hierarchical Deterministic Wallets
BIP62 - Dealing with malleability
BIP66 - Strict DER signatures
BIP340 - Schnorr Signatures for secp256k1
SLIP10 - Universal private key derivation from master private key
EIP-2 - Homestead Hard-fork Changes
EIP-196 - Precompiled contracts for addition and scalar multiplication on the elliptic curve alt_bn128
EIP-197 - Precompiled contracts for optimal ate pairing check on the elliptic curve alt_bn128

Functions
void	BchainCreateXPrvBtcMinikey (string szId, bool isExportable, bool isTemporary)
	Creates an XPriv private key for Bitcoin in minikey format.

void	BchainCreateXPrvBip32 (string szId, byte bVersion, bool isExportable, bool isTemporary)
	Creates an XPriv private key in BIP32 format.

void	BchainCreateXPrvBip32Seed (string szId, DinamoApi.DN_BCHAIN_BIP32_SEED_XPRV_DATA pData, bool isExportable, bool isTemporary)
	Creates an XPriv private key in BIP32 format using seed.

void	BchainCreateXPrvBip39Seed (string szId, DinamoApi.DN_BCHAIN_BIP39_SEED_XPRV_DATA pData, bool isExportable, bool isTemporary)
	Creates an XPriv private key in BIP39 format using seed.

DinamoApi.DN_BCHAIN_KEY_INFO	BchainCreateBip32Ckd (byte bVersion, UInt32 dwIndex, string szPar, string szDst, bool isExportable, bool isTemporary)
	Performs a Child Key Derivation (CKD) operation. Derives an Extended Private Key (XPrv) for the blockchain in the BIP32 standard.

byte[]	BchainSignHash (byte bType, byte bHashMode, byte[] pbHash, string szPk)
	Sign a hash using the Blockchain module.

byte[]	BchainGetPubKey (byte bType, string szId)
	Retrieves a public key using the blockchain module.

byte[]	BchainGetAddress (byte bType, byte bVersion, string szHrp, string szId)
	Retrieves the address of a key using the blockchain module.

byte[]	BchainEdDsaSign (byte bType, string szCtxStr, byte[] pbData, string szId)
	Generates an EdDsa signature using the blockchain module.

void	BchainGenerateKey (Dinamo.Hsm.DinamoClient.KEY_ALG dwAlg, string szId, bool isExportable, bool isTemporary)
	Generates a marked key for use in the blockchain module.

Functions

◆ BchainCreateXPrvBtcMinikey()

void BchainCreateXPrvBtcMinikey	(	string	szId,
		bool	isExportable,
		bool	isTemporary
	)

inline

Creates an XPriv private key for Bitcoin in minikey format.

Parameters

szId	Key identifier.
isExportable	The key can be exported from the HSM.
isTemporary	The key will only exist while the session is active. It will be destroyed after the session is closed.

Exceptions

DinamoException Throws exception in case of error.

◆ BchainCreateXPrvBip32()

void BchainCreateXPrvBip32	(	string	szId,
		byte	bVersion,
		bool	isExportable,
		bool	isTemporary
	)

inline

Creates an XPriv private key in BIP32 format.

Parameters

szId Key identifier.

bVersion

Key version. See table below.

Value	Meaning
DinamoApi.DN_BCHAIN_VER_BIP32_MAINNET	Mainnet BIP32.
DinamoApi.DN_BCHAIN_VER_BIP32_TESTNET	Testnet BIP32.
DinamoApi.DN_BCHAIN_VER_BIP32_HTR_MAINNET	Mainnet BIP32 Hathor.
DinamoApi.DN_BCHAIN_VER_BIP32_HTR_TESTNET	Testnet BIP32 Hathor.

isExportable The key can be exported from the HSM.

isTemporary The key will only exist while the session is active. It will be destroyed after the session is closed.

Exceptions

DinamoException Throws exception in case of error.

Examples: bchain_ckd.cs, bchain_get_address.cs, bchain_get_pub.c s and bchain_sign_hash.cs.

◆ BchainCreateXPrvBip32Seed()

void BchainCreateXPrvBip32Seed	(	string	szId,
		DinamoApi::DN_BCHAIN_BIP32_SEED_XPRV_DATA	pData,
		bool	isExportable,
		bool	isTemporary
	)

inline

Creates an XPriv private key in BIP32 format using seed.

Parameters

szId	Key identifier.
pData	Data for generating the key.
isExportable	The key can be exported from the HSM.
isTemporary	The key will only exist while the session is active. It will be destroyed after the session is closed.

Exceptions

DinamoException Throws exception in case of error.

◆ BchainCreateXPrvBip39Seed()

void BchainCreateXPrvBip39Seed	(	string	szId,
		DinamoApi::DN_BCHAIN_BIP39_SEED_XPRV_DATA	pData,
		bool	isExportable,
		bool	isTemporary
	)

inline

Creates an XPriv private key in BIP39 format using seed.

Parameters

szId	Key identifier.
pData	Data for generating the key.
isExportable	The key can be exported from the HSM.
isTemporary	The key will only exist while the session is active. It will be destroyed after the session is closed.

Exceptions

DinamoException Throws exception in case of error.

◆ BchainCreateBip32Ckd()

DinamoApi.DN_BCHAIN_KEY_INFO BchainCreateBip32Ckd	(	byte	bVersion,
		UInt32	dwIndex,
		string	szPar,
		string	szDst,
		bool	isExportable,
		bool	isTemporary
	)

inline

Performs a Child Key Derivation (CKD) operation. Derives an Extended Private Key (XPrv) for the blockchain in the BIP32 standard.

Parameters

bVersion

Key version. See table below.

Value	Meaning
DinamoApi.DN_BCHAIN_VER_BIP32_MAINNET	Mainnet BIP32.
DinamoApi.DN_BCHAIN_VER_BIP32_TESTNET	Testnet BIP32.
DinamoApi.DN_BCHAIN_VER_BIP32_HTR_MAINNET	Mainnet BIP32 Hathor.
DinamoApi.DN_BCHAIN_VER_BIP32_HTR_TESTNET	Testnet BIP32 Hathor.

dwIndex Index of the key to be derived. Keys non hardened use the 0 a ^231-1 and keys hardened (unrestrictedly secure) use indices of 2³¹ a ^232-1as specified in the standard BIP32. It is highly recommended to generate hardened keys. Use DinamoApi.DN_BCHAIN_SECURE_BIP32_INDEX_BASE as a basis for generating indexes hardened (e.g. DinamoApi.DN_BCHAIN_SECURE_BIP32_INDEX_BASE + 1 ...).

szPar Identifier of the parent key.

szDst Identifier of the derived key. Must be an XPrv key (DinamoApi.DN_BCHAIN_BIP32_XPRV etc.)

isExportable The key can be exported from the HSM.

isTemporary The key will only exist while the session is active. It will be destroyed after the session is closed.

Return: Information on the derived key.

Exceptions

DinamoException Throws exception in case of error.

Examples: bchain_ckd.cs.

◆ BchainSignHash()

byte[] BchainSignHash	(	byte	bType,
		byte	bHashMode,
		byte[]	pbHash,
		string	szPk
	)

inline

Sign a hash using the Blockchain module.

Parameters

bType

Key type.

Value	Meaning
DinamoApi.DN_BCHAIN_SIG_DER_ECDSA	DER signature, in the format v \|\| DER. SECG!SEC1 strict DER with low S as described in BIP62/66, BIP146, EIP2. With 'v' having a size of 1 byte. 'v' is the parity bit of 'r' and can have the values 0 or 1.
DinamoApi.DN_BCHAIN_SIG_RAW_ECDSA	RAW signature, in the format v \|\| r \|\| s. With 'v' having a size of 1 byte and 'r' and 's' each having a size of 32 bytes. 'v' is the parity bit of 'r' and can have the values 0 or 1.
DinamoApi.DN_BCHAIN_SIG_BIP340	Signature BIP340 - Schnorr 64 bytes.

bHashMode

Hash type.

Value	Meaning
DinamoApi.DN_BCHAIN_HASH_BTC_H160	Bitcoin H160.
DinamoApi.DN_BCHAIN_HASH_RIPEMD160	RIPEMD160.
DinamoApi.DN_BCHAIN_HASH_SHA256	SHA256
DinamoApi.DN_BCHAIN_HASH_BTC_SHA256_2X	Bitcoin SHA256 2x.
DinamoApi.DN_BCHAIN_HASH_KECCAK256	KECCAK256.

pbHash Hash calculated according to bHashMode.

szPk Private key identifier.

Return: Signature.

Exceptions

DinamoException Throws exception in case of error.

Examples: bchain_sign_hash.cs.

◆ BchainGetPubKey()

byte[] BchainGetPubKey	(	byte	bType,
		string	szId
	)

inline

Retrieves a public key using the blockchain module.

Parameters

bType

Key type.

Value	Meaning
DinamoApi.DN_BCHAIN_PBK_SEC1_UNCOMP	ECDSA SEC1 uncompressed.
DinamoApi.DN_BCHAIN_PBK_SEC1_COMP	ECDSA SEC1 compressed.
DinamoApi.DN_BCHAIN_PBK_BIP340	Schnorr, BIP-340.
DinamoApi.DN_BCHAIN_PBK_ED25519	Ed25519.
DinamoApi.DN_BCHAIN_PBK_AT_ALGORAND	Algorand.
DinamoApi.DN_BCHAIN_PBK_BIP32_XPUB	BIP32 XPub.
DinamoApi.DN_BCHAIN_PBK_AT_SOL	Solana.

szId Private key identifier.

Return: Public key.

Exceptions

DinamoException Throws exception in case of error.

Examples: bchain_get_pub.cs.

◆ BchainGetAddress()

byte[] BchainGetAddress	(	byte	bType,
		byte	bVersion,
		string	szHrp,
		string	szId
	)

inline

Retrieves the address of a key using the blockchain module.

Parameters

bType

Type of address to be generated. It can be one of the values below.

Value	Meaning
DinamoApi.DN_BCHAIN_AT_BTC_P2PKH	P2PKH address.
DinamoApi.DN_BCHAIN_AT_BTC_P2SH	Address P2SH BIP13..
DinamoApi.DN_BCHAIN_AT_BTC_B32_PKH	Address BIP32 P2PKH BIP173.
DinamoApi.DN_BCHAIN_AT_BTC_B32_SH	BIP32 P2SH address.
DinamoApi.DN_BCHAIN_AT_ETH_EOA	Address ETH EOA.
DinamoApi.DN_BCHAIN_AT_ETH_EOA_MC_CKS	Address ETH EOA MC CKS. EIP55.
DinamoApi.DN_BCHAIN_AT_ETH_EOA_ICAP	Address ETH EOA ICAP.
DinamoApi.DN_BCHAIN_AT_ALGORAND	Address Algorand.
DinamoApi.DN_BCHAIN_AT_TRON_HEX	Hexadecimal TRON address.
DinamoApi.DN_BCHAIN_AT_TRON_B58	Address TRON Base 58.
DinamoApi.DN_BCHAIN_AT_XRP	XRP Ledger/Ripple address.
DinamoApi.DN_BCHAIN_AT_SOL	Address Solana.

Parameters

bVersion

Address version. See table below.

Value	Meaning
DinamoApi.DN_BCHAIN_VER_UNUSED	Parameter not used.
DinamoApi.DN_BCHAIN_VER_BTC_A1_MAIN_NET	Bitcoin A1 mainnet.
DinamoApi.DN_BCHAIN_VER_XRP_CLASSIC	XRP Ledger/Ripple Classic.
DinamoApi.DN_BCHAIN_VER_BTC_AMN_TEST_NET	Bitcoin P2PKH testnet.
DinamoApi.DN_BCHAIN_VER_BTC_A3_MAIN_NET	Bitcoin A3 mainnet.
DinamoApi.DN_BCHAIN_VER_BTC_B32_WITVER	Bitcoin B32 witver.
DinamoApi.DN_BCHAIN_VER_HTR_MAINNET	Hathor mainnet.
DinamoApi.DN_BCHAIN_VER_HTR_TESTNET	Hathor testnet.
DinamoApi.DN_BCHAIN_VER_HTR_P2SH_MAINNET	Hathor P2SH mainnet.
DinamoApi.DN_BCHAIN_VER_HTR_P2SH_TESTNET	Hathor P2SH testnet.

szHrp

HRP (Human Readable Part) of the key. The values in the table are accepted. Must have a maximum size of DinamoApi.DN_BCHAIN_MAX_HRP

Value	Meaning
DinamoApi.DN_BCHAIN_HRP_UNUSED	Parameter not used.
DinamoApi.DN_BCHAIN_HRP_BTC_MAIN_NET	Bitcoin mainnet.
DinamoApi.DN_BCHAIN_HRP_BTC_TEST_NET	Bitcoin testnet.

szId Private key identifier.

Return: Address.

Exceptions

DinamoException Throws exception in case of error.

Examples: bchain_get_address.cs.

◆ BchainEdDsaSign()

byte[] BchainEdDsaSign	(	byte	bType,
		string	szCtxStr,
		byte[]	pbData,
		string	szId
	)

inline

Generates an EdDsa signature using the blockchain module.

Parameters

bType

Type of subscription to be generated. It can be one of the values below.

Value	Meaning
DinamoApi.DN_BCHAIN_EDDSA_SIG_PURE	EdDsa Pure Signature.
DinamoApi.DN_BCHAIN_EDDSA_SIG_ALGORAND	EdDsa Algorand Signature.
DinamoApi.DN_BCHAIN_EDDSA_SIG_XRP	EdDsa XRP subscription.
DinamoApi.DN_BCHAIN_EDDSA_SIG_SOL	Signature EdDsa Solana.

szCtxStr Context string as defined in RFC-8032 of maximum size DinamoApi.DN_BCHAIN_EDDSA_MAX_CSTRL. Can be passed DinamoApi.DN_BCHAIN_EDDSA_CSTR_UNUSED.

pbData Data to be signed.

szId Private key identifier.

Return: Signature.

Exceptions

DinamoException Throws exception in case of error.

Examples: bchain_eddsa_sign.cs.

◆ BchainGenerateKey()

void BchainGenerateKey	(	Dinamo::Hsm::DinamoClient::KEY_ALG	dwAlg,
		string	szId,
		bool	isExportable,
		bool	isTemporary
	)

inline

Generates a marked key for use in the blockchain module.

Parameters

dwAlg	Algorithm to be used. Dinamo.Hsm.DinamoClient.KEY_ALG
szId	Key identifier.
isExportable	The key can be exported from the HSM.
isTemporary	The key will only exist while the session is active. It will be destroyed after the session is closed.

Exceptions

DinamoException Throws exception in case of error.

Examples: bchain_eddsa_sign.cs.