Utilities

Wallet Management

This section details the functions within the Blocklet SDK that facilitate the management of the Blocklet's internal wallet and its associated cryptographic operations. These utilities are crucial for enabling secure communication, data handling, and identity verification within your Blocklet application.
For information on user authentication and DID-related user information, refer to the Auth Service section.
Managing the Blocklet's Wallet#The Blocklet SDK provides several functions to access and manage the Blocklet application's wallet, which is essential for signing requests and other cryptographic operations.
getWallet#Retrieves the Blocklet application's default wallet. This function caches wallet instances for performance.
Parameters
Name
Type
Description
type
DIDTypeShortcut (optional)
The type of DID wallet, e.g., 'eth', 'ethereum', 'default', 'arcblock'. Defaults to process.env.CHAIN_TYPE or process.env.BLOCKLET_WALLET_TYPE.
appSk
string (optional)
The application's secret key in hexadecimal format. Defaults to process.env.BLOCKLET_APP_SK.
Returns
Name
Type
Description
wallet
WalletObject
The WalletObject instance representing the Blocklet's application wallet.
Example
import { getWallet } from '@blocklet/sdk';

async function retrieveDefaultWallet() {
  try {
    const wallet = getWallet();
    console.log('Default Blocklet Wallet DID:', wallet.did);
  } catch (error) {
    console.error('Error getting default wallet:', error.message);
  }
}

retrieveDefaultWallet();

async function retrieveEthereumWallet() {
  try {
    const ethWallet = getWallet('ethereum');
    console.log('Ethereum-type Blocklet Wallet DID:', ethWallet.did);
  } catch (error) {
    console.error('Error getting Ethereum wallet:', error.message);
  }
}

retrieveEthereumWallet();Example Response
Default Blocklet Wallet DID: did:abt:z************
Ethereum-type Blocklet Wallet DID: did:eth:0x************This example demonstrates how to retrieve the default Blocklet application wallet and an Ethereum-compatible wallet.
getPermanentWallet#Retrieves the Blocklet application's permanent wallet. This wallet is typically used for long-lived operations or when the ephemeral BLOCKLET_APP_SK might change. It uses process.env.BLOCKLET_APP_PSK.
Parameters
None.
Returns
Name
Type
Description
wallet
WalletObject
The WalletObject instance representing the Blocklet's permanent application wallet.
Example
import { getWallet } from '@blocklet/sdk';

async function retrievePermanentWallet() {
  try {
    const permanentWallet = getWallet.getPermanentWallet();
    console.log('Permanent Blocklet Wallet DID:', permanentWallet.did);
  } catch (error) {
    console.error('Error getting permanent wallet:', error.message);
  }
}

retrievePermanentWallet();Example Response
Permanent Blocklet Wallet DID: did:abt:z************This example retrieves the Blocklet's permanent application wallet.
getEthereumWallet#Retrieves the Blocklet application's Ethereum-compatible wallet. You can specify whether to get the permanent or ephemeral Ethereum wallet.
Parameters
Name
Type
Description
permanent
boolean (optional)
If true, retrieves the permanent Ethereum wallet using BLOCKLET_APP_PSK. Defaults to false, using BLOCKLET_APP_SK.
Returns
Name
Type
Description
wallet
WalletObject
The WalletObject instance representing the Blocklet's Ethereum-compatible wallet.
Example
import { getWallet } from '@blocklet/sdk';

async function retrieveSpecificEthereumWallet() {
  try {
    const ephemeralEthWallet = getWallet.getEthereumWallet();
    console.log('Ephemeral Ethereum Wallet DID:', ephemeralEthWallet.did);

    const permanentEthWallet = getWallet.getEthereumWallet(true);
    console.log('Permanent Ethereum Wallet DID:', permanentEthWallet.did);
  } catch (error) {
    console.error('Error getting Ethereum wallet:', error.message);
  }
}

retrieveSpecificEthereumWallet();Example Response
Ephemeral Ethereum Wallet DID: did:eth:0x************
Permanent Ethereum Wallet DID: did:eth:0x************This example demonstrates retrieving both the ephemeral and permanent Ethereum-compatible wallets.
getPkWallet#Retrieves a WalletObject instance from a public key, allowing you to perform operations that only require a public key.
Parameters
Name
Type
Description
type
DIDTypeShortcut (optional)
The type of DID, e.g., 'eth', 'ethereum', 'default', 'arcblock'. Defaults to process.env.CHAIN_TYPE or process.env.BLOCKLET_WALLET_TYPE.
appPk
string (optional)
The application's public key in hexadecimal format. Defaults to process.env.BLOCKLET_APP_PK.
Returns
Name
Type
Description
wallet
WalletObject
The WalletObject instance derived from the provided public key.
Example
import { getWallet } from '@blocklet/sdk';

async function retrieveWalletFromPublicKey() {
  try {
    // Assuming process.env.BLOCKLET_APP_PK is set
    const pkWallet = getWallet.getPkWallet();
    console.log('Wallet from Public Key DID:', pkWallet.did);
  } catch (error) {
    console.error('Error getting wallet from public key:', error.message);
  }
}

retrieveWalletFromPublicKey();Example Response
Wallet from Public Key DID: did:abt:z************This example retrieves a wallet object using the application's public key.
Cryptographic Operations#The Blocklet SDK provides helper functions for common cryptographic tasks such as encryption, decryption, and response signing/verification, leveraging the Blocklet's internal wallet.
encrypt#Encrypts a given message using AES encryption. It uses process.env.BLOCKLET_APP_EK as the default password and process.env.BLOCKLET_DID as the default salt.
Parameters
Name
Type
Description
message
string
The message string to encrypt.
password
string (optional)
The encryption password. Defaults to process.env.BLOCKLET_APP_EK.
salt
string (optional)
The salt for key derivation. Defaults to process.env.BLOCKLET_DID.
Returns
Name
Type
Description
encryptedMessage
string
The encrypted message string.
Example
import { encrypt } from '@blocklet/sdk/lib/security';

async function encryptData() {
  const originalMessage = 'Sensitive data to be protected.';
  const encrypted = encrypt(originalMessage);
  console.log('Encrypted message (using default env vars):', encrypted);

  const customEncrypted = encrypt(originalMessage, 'myCustomPassword', 'myCustomSalt');
  console.log('Encrypted message (using custom credentials):', customEncrypted);
}

encryptData();Example Response
Encrypted message (using default env vars): U2FsdGVkX1************
Encrypted message (using custom credentials): U2FsdGVkX1************This example shows how to encrypt a string, using both default environment variables and custom credentials.
decrypt#Decrypts an encrypted message using AES decryption. It uses process.env.BLOCKLET_APP_EK as the default password and process.env.BLOCKLET_DID as the default salt.
Parameters
Name
Type
Description
message
string
The encrypted message string to decrypt.
password
string (optional)
The decryption password. Defaults to process.env.BLOCKLET_APP_EK.
salt
string (optional)
The salt used during encryption. Defaults to process.env.BLOCKLET_DID.
Returns
Name
Type
Description
decryptedMessage
string
The decrypted message string.
Example
import { encrypt, decrypt } from '@blocklet/sdk/lib/security';

async function encryptAndDecryptData() {
  const originalMessage = 'Another piece of sensitive data.';

  const encrypted = encrypt(originalMessage);
  const decrypted = decrypt(encrypted);
  console.log('Original:', originalMessage);
  console.log('Decrypted (using default env vars):', decrypted);

  const customEncrypted = encrypt(originalMessage, 'myCustomPassword', 'myCustomSalt');
  const customDecrypted = decrypt(customEncrypted, 'myCustomPassword', 'myCustomSalt');
  console.log('Decrypted (using custom credentials):', customDecrypted);
}

encryptAndDecryptData();Example Response
Original: Another piece of sensitive data.
Decrypted (using default env vars): Another piece of sensitive data.
Decrypted (using custom credentials): Another piece of sensitive data.This example demonstrates encrypting and then decrypting a string, verifying that the original message is recovered.
signResponse#Signs an API response object using the Blocklet application's default wallet. This is typically used to ensure the integrity and authenticity of data sent from your Blocklet.
Parameters
Name
Type
Description
data
any
The data object to be signed.
Returns
Name
Type
Description
signedData
any
The signed data object, typically including a signature and signer field.
Example
import { signResponse } from '@blocklet/sdk/lib/security';

async function signApiResponse() {
  const responseData = { status: 'success', message: 'Data fetched successfully' };
  const signed = signResponse(responseData);
  console.log('Signed response:', JSON.stringify(signed, null, 2));
}

signApiResponse();Example Response
{
  "status": "success",
  "message": "Data fetched successfully",
  "signature": "0x...",
  "signer": "did:abt:z..."
}This example demonstrates how to sign a response object, adding a digital signature and the signer's DID to the data.
verifyResponse#Verifies the signature of an API response object. This function checks the integrity and authenticity of data received from other Blocklets or services by validating its digital signature against the signer's public key.
Parameters
Name
Type
Description
data
any
The data object with a signature and signer field to be verified.
Returns
Name
Type
Description
isValid
boolean
true if the signature is valid, false otherwise.
Example
import { signResponse, verifyResponse } from '@blocklet/sdk/lib/security';

async function verifyApiResponse() {
  const originalData = { status: 'success', message: 'Data to be signed and verified' };
  const signedData = signResponse(originalData);

  const isValid = verifyResponse(signedData);
  console.log('Is the response signature valid?', isValid);

  // Example of tampered data
  const tamperedData = { ...signedData, message: 'Tampered data' };
  const isTamperedValid = verifyResponse(tamperedData);
  console.log('Is the tampered response signature valid?', isTamperedValid);
}

verifyApiResponse();Example Response
Is the response signature valid? true
Is the tampered response signature valid? falseThis example demonstrates how to sign a data object and then verify its signature, showing that tampering with the data invalidates the signature.

This section provided a detailed overview of wallet management and cryptographic operations within the Blocklet SDK. You can now securely handle your Blocklet's identity and data. Continue to the Environment & Config section to learn how to access Blocklet environment variables and SDK configuration settings.

Name	Type	Description
`type`	`DIDTypeShortcut` (optional)	The type of DID wallet, e.g., `'eth'`, `'ethereum'`, `'default'`, `'arcblock'`. Defaults to `process.env.CHAIN_TYPE` or `process.env.BLOCKLET_WALLET_TYPE`.
`appSk`	`string` (optional)	The application's secret key in hexadecimal format. Defaults to `process.env.BLOCKLET_APP_SK`.

Name	Type	Description
`type`	`DIDTypeShortcut` (optional)	The type of DID, e.g., `'eth'`, `'ethereum'`, `'default'`, `'arcblock'`. Defaults to `process.env.CHAIN_TYPE` or `process.env.BLOCKLET_WALLET_TYPE`.
`appPk`	`string` (optional)	The application's public key in hexadecimal format. Defaults to `process.env.BLOCKLET_APP_PK`.

Name	Type	Description
`message`	`string`	The message string to encrypt.
`password`	`string` (optional)	The encryption password. Defaults to `process.env.BLOCKLET_APP_EK`.
`salt`	`string` (optional)	The salt for key derivation. Defaults to `process.env.BLOCKLET_DID`.

Name	Type	Description
`message`	`string`	The encrypted message string to decrypt.
`password`	`string` (optional)	The decryption password. Defaults to `process.env.BLOCKLET_APP_EK`.
`salt`	`string` (optional)	The salt used during encryption. Defaults to `process.env.BLOCKLET_DID`.

Overview

Get Started

Core Services

Middleware Reference

Utilities

Advanced Topics

API Reference

Wallet Management

Managing the Blocklet's Wallet#

`getWallet`#

`getPermanentWallet`#

`getEthereumWallet`#

`getPkWallet`#

Cryptographic Operations#

`encrypt`#

`decrypt`#

`signResponse`#

`verifyResponse`#

Utilities

Environment & Config