SDK
Ethereum
This package provides functionalities to interact with 4thTech protocol on Ethereum blockchain.
Installation
npm install @4thtech-sdk/ethereum
Class that handles sending, retrieving and listening for events related to mail storage on-chain.
Initialization
Initialize a new mail client.
Param | Type | Description |
---|---|---|
config | MailConfig | The 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.
Param | Type | Description |
---|---|---|
options | MailSendOptions | Configuration for sending mail. |
options.envelope | Envelope | The mail envelope to send. |
[options.encryption] | Encryption | Optional encryption method. |
[options.onStateChange] | function | Optional callback to track state changes during sending. |
[options.onUploadProgress] | function | Optional 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.
Param | Type | Description |
---|---|---|
mailIndex | BigNumberish | The 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.
Param | Type | Description |
---|---|---|
receiver | string | The mail receiver address. |
mailIndex | BigNumberish | The 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.
Param | Type | Description |
---|---|---|
receiver | string | The 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.
Param | Type | Description |
---|---|---|
receiver | string | The 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.
Param | Type | Description |
---|---|---|
transactionHash | TransactionHash | The transaction hash. |
const receivedEnvelope = await mail.fetchByTransactionHash(transactionHash);
count
The count
method is used to count the number of mails sent to a receiver.
Param | Type | Description |
---|---|---|
receiver | string | The mail receiver address. |
const mailCount = await mail.count(receiver);
getUserAppIds
The getUserAppIds
method is used to retrieves the user's App ID's.
Param | Type | Description |
---|---|---|
user | string | The user address. |
const appIds = await mail.getUserAppIds(user);
downloadAttachment
The downloadAttachment
method is used to download an attachment from a mail.
Param | Type | Description |
---|---|---|
attachment | RemoteFileInfo | The 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.
Param | Type | Description |
---|---|---|
mailIndex | BigNumberish | The 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.
Param | Type | Description |
---|---|---|
mailIndexes | Array.<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.
Param | Type | Description |
---|---|---|
sender | string | null | The mail sender address. |
receiver | string | null | The mail receiver address. |
callback | function | The 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.
Param | Type | Description |
---|---|---|
receiver | string | null | The mail receiver address. |
index | BigNumberish | null | The index of the mail. |
callback | function | The 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.
Param | Type | Description |
---|---|---|
receiver | string | null | The mail receiver address. |
index | BigNumberish | null | The index of the mail. |
callback | function | The 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.
Param | Type | Description |
---|---|---|
config | UserConfig | The 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
Param | Type | Description |
---|---|---|
publicKey | string | The user's public key of an encryption method. |
publicKeyType | string | The 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.
Param | Type | Description |
---|---|---|
user | string | The 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.
Param | Type | Description |
---|---|---|
user | string | The user address. |
callback | function | A callback function. |
user.onEncryptionPublicKeySet(user, (user, publicKey, publicKeyType) => {
console.log(user);
console.log(publicKey);
console.log(publicKeyType);
})