SDK

Ethereum

This package provides functionalities to interact with 4thTech protocol on Ethereum blockchain.


Installation

npm install @4thtech-sdk/ethereum

Mail

Class that handles sending, retrieving and listening for events related to mail storage on-chain.

Initialization

Initialize a new mail client.

ParamTypeDescription
configMailConfigThe configuration for the mail client.
import { Mail, MailConfig } from '@4thtech-sdk/ethereum';
import { MailReadyChain } from '@4thtech-sdk/types';

const config: MailConfig = {
  signer,
  chain: sepolia as MailReadyChain,
  remoteStorageProvider,
  appId, // optional
  encryptionHandler, // optional
};

const mail = new Mail(config);

send

The send method is used to send a new mail. It requires an Envelope object within the options parameter, detailing the mail's content, receiver, and sender. Optionally you can attach Encryption method which will be used for data encryption.

ParamTypeDescription
optionsMailSendOptionsConfiguration for sending mail.
options.envelopeEnvelopeThe mail envelope to send.
[options.encryption]EncryptionOptional encryption method.
[options.onStateChange]functionOptional callback to track state changes during sending.
[options.onUploadProgress]functionOptional callback to track files upload progress.
import { AesEncryption } from '@4thtech-sdk/encryption';
import { Envelope } from '@4thtech-sdk/types';

const envelope: Envelope = { ... };

const aesEncryption = new AesEncryption();
await aesEncryption.generateSecretKey();

const txResponse = await mail.send({
  envelope,
  encryption: aesEncryption,
  onStateChange: (state) => {
    console.log(state);
  },
  onUploadProgress: (progressInfo) => {
    console.log(`Upload Progress (${progressInfo.fileName}): ${progressInfo.percent}%`);
  },
});

setOpenedAt

The setOpenedAt method is used to set opened time for a specific mail. This method can only perform a receiver of the mail.

ParamTypeDescription
mailIndexBigNumberishThe index of the mail to set opened time.
const txResponse = await mail.setOpenedAt(mailIndex);

fetch

The fetch method is used to fetch a specific mail sent to a receiver at a given index.

ParamTypeDescription
receiverstringThe mail receiver address.
mailIndexBigNumberishThe index of the mail.
const receivedEnvelope = await mail.fetch(receiver, mailIndex);

fetchAll

The fetchAll method is used to fetch all mails sent to a receiver.

ParamTypeDescription
receiverstringThe mail receiver address.
const receivedEnvelopes = await mail.fetchAll(receiver);

fetchPaginated

The fetchPaginated method is used to fetch a specified number of mails sent to a receiver, in a paginated manner. This can be helpful when dealing with a large number of mails, as it allows you to load and process a manageable number of mails at a time.

ParamTypeDescription
receiverstringThe mail receiver address.
const receivedEnvelopes = await mail.fetchPaginated(receiver, pageNumber, pageSize);

fetchByTransactionHash

The fetchByTransactionHash method is used to fetch a mail associated with a specific transaction hash.

ParamTypeDescription
transactionHashTransactionHashThe transaction hash.
const receivedEnvelope = await mail.fetchByTransactionHash(transactionHash);

count

The count method is used to count the number of mails sent to a receiver.

ParamTypeDescription
receiverstringThe mail receiver address.
const mailCount = await mail.count(receiver);

getUserAppIds

The getUserAppIds method is used to retrieves the user's App ID's.

ParamTypeDescription
userstringThe user address.
const appIds = await mail.getUserAppIds(user);

downloadAttachment

The downloadAttachment method is used to download an attachment from a mail.

ParamTypeDescription
attachmentRemoteFileInfoThe attachment information.
const fileContent = await mail.downloadAttachment(attachment);

deleteMail

The deleteMail method is used to delete a specific mail from a user's mails. This method can only perform a receiver of the mail.

ParamTypeDescription
mailIndexBigNumberishThe index of the mail to be deleted.
const txResponse = await mail.deleteMail(mailIndex);

deleteMails

The deleteMails method is used to delete multiple mails from a user's mails at once.
This can be particularly helpful in scenarios where a user might want to perform batch operations and delete several mails simultaneously. This method can only perform a receiver of the mails.

ParamTypeDescription
mailIndexesArray.<BigNumberish>The indexes of mails to be deleted.
const txResponse = await mail.deleteMails(mailIndexes);

onNew

The onNew method is used to set up event listener for new mail event. You can set up listeners for received mails, sent mails, or all mails.

ParamTypeDescription
senderstring | nullThe mail sender address.
receiverstring | nullThe mail receiver address.
callbackfunctionThe callback function.
// Listen to received mails
mail.onNew(null, receiver, (envelope) => {
  console.log(envelope);
});

// Listen to sent mails
mail.onNew(sender, null, (envelope) => {
  console.log(envelope);
});

// Listen to all mails
mail.onNew(null, null, (envelope) => {
  console.log(envelope);
});

onOpened

The onOpened method is used to set up event listener for opened mail event.

ParamTypeDescription
receiverstring | nullThe mail receiver address.
indexBigNumberish | nullThe index of the mail.
callbackfunctionThe callback function.
// Listen to all opened mails for a receiver
mail.onOpened(receiver, null, (index, openedAt) => {
  console.log(index);
  console.log(openedAt);
});

// Listen to a specific opened mail for a receiver
mail.onOpened(receiver, index, (index, openedAt) => {
  console.log(index);
  console.log(openedAt);
});

// Listen to all opened mails
mail.onOpened(null, null, (index, openedAt) => {
  console.log(index);
  console.log(openedAt);
});

onDeleted

The onDeleted method is used to set up event listener for deleted mail event.

ParamTypeDescription
receiverstring | nullThe mail receiver address.
indexBigNumberish | nullThe index of the mail.
callbackfunctionThe callback function.
// Listen to all deleted mails for a receiver
mail.onDeleted(receiver, null, (index, deletedAt) => {
  console.log(index);
  console.log(deletedAt);
});

// Listen to a specific deleted mail for a receiver
mail.onDeleted(receiver, index, (index, deletedAt) => {
  console.log(index);
  console.log(deletedAt);
});

// Listen to all deleted mails
mail.onDeleted(null, null, (index, deletedAt) => {
  console.log(index);
  console.log(deletedAt);
});

User

Class that handles storing, retrieving and listening for events related to user storage on-chain.

Initialization

Initialize a new user client.

ParamTypeDescription
configUserConfigThe configuration for the user client.
import { User, UserConfig } from '@4thtech-sdk/ethereum';

const config: UserContractConfig = {
  signer,
  chain: sepolia as UserReadyChain,
};

const user = new User(config);

setEncryptionPublicKey

ParamTypeDescription
publicKeystringThe user's public key of an encryption method.
publicKeyTypestringThe public key type for an encryption method.

The setEncryptionPublicKey method is used to set the encryption public key of a user.

const txResponse = await user.setEncryptionPublicKey(publicKey, publicKeyType);

fetch

The fetch method is used to retrieve the details of a user, like an encryption public key.

ParamTypeDescription
userstringThe user address.
const receivedUser = await user.fetch(user);

onEncryptionPublicKeySet

The onEncryptionPublicKeySet method is used to set up event listener for when encryption public key is set event.

ParamTypeDescription
userstringThe user address.
callbackfunctionA callback function.
user.onEncryptionPublicKeySet(user, (user, publicKey, publicKeyType) => {
  console.log(user);
  console.log(publicKey);
  console.log(publicKeyType);
})
Previous
Wallets