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.

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.

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.

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.

const receivedEnvelope = await mail.fetch(receiver, mailIndex);

fetchAll

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

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.

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

fetchByTransactionHash

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

const receivedEnvelope = await mail.fetchByTransactionHash(transactionHash);

count

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

const mailCount = await mail.count(receiver);

getUserAppIds

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

const appIds = await mail.getUserAppIds(user);

downloadAttachment

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

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.

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.

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.

// 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.

// 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.

// 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.

import { User, UserConfig } from '@4thtech-sdk/ethereum';

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

const user = new User(config);

setEncryptionPublicKey

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.

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.

user.onEncryptionPublicKeySet(user, (user, publicKey, publicKeyType) => {
  console.log(user);
  console.log(publicKey);
  console.log(publicKeyType);
})