Ephemeral Deposits

Using ephemeral 0x-accounts served on the library side

The ephemeral deposit scheme was designed to give the ability to deposit to a zk-account from the smart contracts (e.g. bridges). The idea is to temporary give control over the deposited funds to some EOA, which can then make a regular permittable deposit.

Such an EOA is an ad-hoc generated account derived from the zk-account spending key. So the library controls ephemeral private keys and has full access over the funds on the ephemeral addresses

Since deposits to a single zkBob account can be made from different smart contract wallets, reusing the same ephemeral EOA address is not a good idea, as it can be used to link together independent deposits. A better option is to use a newly generated EOA address for each new deposit.

Using ephemeral deposit scheme is an early developed feature. At now the direct deposits are more suitable to process external deposits

Sending Ephemeral Deposits

To use an ephemeral deposit you should send funds to the ephemeral address first. The address must have a sufficient balance to process the deposit and cover the relayer fee.

async depositEphemeral(
    amountGwei: bigint,
    ephemeralIndex: number,
    relayerFee?: RelayerFee,
): Promise<string>

Parameters

amountGwei - token amount to deposit into an account (in pool dimension).

ephemeralIndex - an index of the ephemeral address.

relayerFee - a raw relayer fee object which will be used to estimate the total transaction fee (will requested under the hood when undefined).

Returns

Promise returns jobId returned by relayer which can be use to monitor the transaction.

Example

const myAddress = await zkClient.directDeposit(90000000000n, 0);
console.log(`Ephemeral deposit sent to the relayer (job ID = ${jobId})`)
// output: Ephemeral deposit sent to the relayer (job ID = 4736)

Getting the First Non-Used Ephemeral Address Index

Scanning over the ephemeral addresses pool to find the first address which was not in use. The address is considering to be non-used if token balance, native balance, native and permit nonces are zero.

async getNonusedEphemeralIndex(): Promise<number>

Returns

Promise returns index of the first non-used ephemeral address.

Example

const idx = await getNonusedEphemeralIndex();
console.log(`Found nonused ephemeral address at index ${idx}`);
// output: Found nonused ephemeral address at index 3

Getting Ephemeral Address at Index

The library generates ephemeral addresses with BIP32 (hierarchical deterministic wallets). So the every address has an index (the last HD path component).

async getEphemeralAddress(index: number): Promise<EphemeralAddress>

Parameters

index - an index of requested ephemeral address.

Returns

Promise returns EphemeralAddress object.

Example

const ephAddr = await getEphemeralAddress(0);
console.log(`First ephemeral address: ${ephAddr.address}`);
// output: First ephemeral address: 0x8ff66a5491a15ac67c596d1e9a6290e56dd4d156

Getting All Used Ephemeral Addresses

Request details of all ephemeral addresses which were already used.

async getUsedEphemeralAddresses(): Promise<EphemeralAddress[]>

Returns

Promise returns array of EphemeralAddress objects.

Example

const used = await getUsedEphemeralAddresses();
console.log(`$Used addresses: {used.map((a) => a.address).join(`,\n`)}`);
// output: Used addresses: 0x8ff66a5491a15ac67c596d1e9a6290e56dd4d156,
//         0x8434e839e0fa967fb7b9f624c381d533bcbce05d,
//         0xa78b9d09b307a972cae3be39f9182b7065fb15f4

Retrieving Number of Token Transfers To the Address

async getEphemeralAddressInTxCount(index: number): Promise<number>

Parameters

index - an index of the ephemeral address.

Returns

Promise returns number of incoming token transfers to the ephemeral address with the requested index.

Example

const cnt = await getEphemeralAddressInTxCount(0);
console.log(`Incoming token transfers: ${cnt}`);
// output: Incoming token transfers: 1

Retrieving Number of Token Transfers From the Address

async getEphemeralAddressInTxCount(index: number): Promise<number>

Parameters

index - an index of the ephemeral address

Returns

Promise returns number of outgoing token transfers to the ephemeral address with the requested index.

Example

const cnt = await getEphemeralAddressInTxCount(0);
console.log(`Outgoing token transfers: ${cnt}`);
// output: Outgoing token transfers: 1

Getting the Ephemeral Address Private Key

Use this method only for emergency reasons. Everyone who has the private key has full control over the funds on that ephemeral address.

getEphemeralAddressPrivateKey(index: number): string

Parameters

index - an index of the ephemeral address

Returns

A string with the private key in the hex representation

Example

const privKey = getEphemeralAddressPrivateKey(1);
console.log(`Private key: ${privKey}`);
// output: Private key: 2c7c5924e695bd0aad2145641f92fe3d95faf13d236dba7978c138fb6045ba3c