Skip to content

Commit

Permalink
add docs for methods
Browse files Browse the repository at this point in the history
  • Loading branch information
@avkos
avkos committed Feb 6, 2024
1 parent 64d23e5 commit b779027
Show file tree
Hide file tree
Showing 2 changed files with 148 additions and 42 deletions.
55 changes: 23 additions & 32 deletions src/plugin.ts
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
import type { Address } from 'web3';
import { Web3PluginBase, Contract } from 'web3';
import { toBigInt } from 'web3-utils';
import type { Web3RequestManager } from 'web3-core';
import { ERC20TokenAbi } from './contracts/ERC20Token';
import { RpcMethods } from './rpc.methods';
import { ETH_ADDRESS, ZERO_ADDRESS } from './constants';
import { L2BridgeAbi } from './contracts/L2Bridge';
import type { TokenInfo, WalletBalances } from './types';

export class ZkSyncPlugin extends Web3PluginBase {
public pluginNamespace = 'zkSync';
Expand All @@ -29,6 +27,9 @@ export class ZkSyncPlugin extends Web3PluginBase {
this._erc20Contracts = {};
}

/**
* Get RPC methods instance
*/
get rpc(): RpcMethods {
if (!this._rpc) {
this._rpc = new RpcMethods(
Expand All @@ -38,6 +39,10 @@ export class ZkSyncPlugin extends Web3PluginBase {
return this._rpc;
}

/**
* Get L2 bridge contract instance
* @param address - Contract address
*/
getL2BridgeContract(address: Address): Contract<typeof L2BridgeAbi> {
if (!this._l2BridgeContracts[address]) {
this._l2BridgeContracts[address] = new Contract(L2BridgeAbi, address);
Expand All @@ -46,6 +51,10 @@ export class ZkSyncPlugin extends Web3PluginBase {
return this._l2BridgeContracts[address];
}

/**
* Get the ERC20 contract instance
* @param address - Contract address
*/
erc20(address: string): Contract<typeof ERC20TokenAbi> {
if (!this._erc20Contracts[address]) {
this._erc20Contracts[address] = new Contract(ERC20TokenAbi, address);
Expand All @@ -54,6 +63,9 @@ export class ZkSyncPlugin extends Web3PluginBase {
return this._erc20Contracts[address];
}

/**
* Get the default bridge addresses
*/
async getDefaultBridgeAddresses(): Promise<{
erc20L1: Address;
erc20L2: Address;
Expand All @@ -75,7 +87,11 @@ export class ZkSyncPlugin extends Web3PluginBase {
};
}

async getL1Address(token: Address): Promise<string> {
/**
* Get the L1 address of a token
* @param token - The address of the token
*/
async getL1Address(token: Address): Promise<Address> {
if (token == ETH_ADDRESS) {
return ETH_ADDRESS;
} else {
Expand All @@ -96,6 +112,10 @@ export class ZkSyncPlugin extends Web3PluginBase {
}
}

/**
* Get the L2 address of a token
* @param token - The address of the token
*/
async getL2Address(token: Address): Promise<string> {
if (token == ETH_ADDRESS) {
return ETH_ADDRESS;
Expand All @@ -117,35 +137,6 @@ export class ZkSyncPlugin extends Web3PluginBase {
return erc20Bridge.methods.l2TokenAddress(token).call();
}
}

async accountBalances(address: Address): Promise<WalletBalances> {
const balances = await this.rpc.getAllAccountBalances(address);
const result: { [key: string]: bigint } = {};
for (const b of Object.keys(balances)) {
result[b] = toBigInt(balances[b] as bigint);
}
return result;
}

getERC20BalanceByAddress(tokenAddress: Address, address: Address): Promise<bigint> {
return this.erc20(tokenAddress).methods.balanceOf(address).call();
}

async getErc20TokenInfo(tokenAddress: Address): Promise<TokenInfo> {
const erc20Contract = this.erc20(tokenAddress);
const [name, symbol, decimals, totalSupply] = await Promise.all([
erc20Contract.methods.name().call(),
erc20Contract.methods.symbol().call(),
erc20Contract.methods.decimals().call(),
erc20Contract.methods.totalSupply().call(),
]);
return {
name,
symbol,
decimals: BigInt(decimals),
totalSupply: BigInt(totalSupply),
};
}
}

// Module Augmentation
Expand Down
135 changes: 125 additions & 10 deletions src/rpc.methods.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,38 +46,74 @@ export class RpcMethods {
});
}

/**
* Returns the chain id of the underlying L1.
*
* @param returnFormat - The format of the return value.
*/
public async l1ChainId(returnFormat: DataFormat = DEFAULT_RETURN_FORMAT): Promise<bigint> {
return format(IntSchema, await this._send('zks_L1ChainId', []), returnFormat) as bigint;
}

/**
* Returns the latest L1 batch number.
*
* @param returnFormat - The format of the return value.
*/
public async getL1BatchNumber(
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
): Promise<bigint> {
return format(IntSchema, await this._send('zks_L1BatchNumber', []), returnFormat) as bigint;
}

/**
* Returns data pertaining to a given batch.
*
* @param number - The layer 1 batch number.
* @param returnFormat - The format of the return value.
*/
public async getL1BatchDetails(
number: number,
number: Numbers,
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
): Promise<BatchDetails> {
return format(
BatchDetailsSchema,
await this._send('zks_getL1BatchDetails', [number]),
await this._send('zks_getL1BatchDetails', [
typeof number === 'bigint' ? number.toString() : number,
]),
returnFormat,
) as BatchDetails;
}

/**
* Returns additional zkSync-specific information about the L2 block.
*
* committed: The batch is closed and the state transition it creates exists on layer 1.
* proven: The batch proof has been created, submitted, and accepted on layer 1.
* executed: The batch state transition has been executed on L1; meaning the root state has been updated.
*
* @param number - The number of the block.
* @param returnFormat - The format of the return value.
*/
public async getBlockDetails(
number: number,
number: Numbers,
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
): Promise<BlockDetails> {
return format(
BlockDetailsSchema,
await this._send('zks_getBlockDetails', [number]),
await this._send('zks_getBlockDetails', [
typeof number === 'bigint' ? number.toString() : number,
]),
returnFormat,
) as BlockDetails;
}

/**
* Returns data from a specific transaction given by the transaction hash.
*
* @param txHash - Transaction hash as string.
* @param returnFormat - The format of the return value.
*/
public async getTransactionDetails(
txHash: Bytes,
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
Expand All @@ -89,6 +125,12 @@ export class RpcMethods {
) as TransactionDetails;
}

/**
* Returns bytecode of a transaction given by its hash.
*
* @param bytecodeHash - Bytecode hash as string.
* @param returnFormat - The format of the return value.
*/
public async getBytecodeByHash(
bytecodeHash: Bytes,
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
Expand All @@ -100,18 +142,33 @@ export class RpcMethods {
) as Uint8Array;
}

/**
* Returns data of transactions in a block.
*
* @param number - Block number.
* @param returnFormat - The format of the return value.
*/
public async getRawBlockTransactions(
number: number,
number: Numbers,
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
): Promise<RawBlockTransaction[]> {
const result = await this._send('zks_getRawBlockTransactions', [number]);
const result = await this._send('zks_getRawBlockTransactions', [
typeof number === 'bigint' ? number.toString() : number,
]);
if (Array.isArray(result)) {
return result.map(tx => {
return format(RawBlockTransactionSchema, tx, returnFormat) as RawBlockTransaction;
});
}
return [];
}

/**
* Returns the fee for the transaction.
*
* @param transaction - Transaction object.
* @param returnFormat - The format of the return value.
*/
public async estimateFee(
transaction: Partial<TransactionWithSenderAPI>,
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
Expand All @@ -122,6 +179,13 @@ export class RpcMethods {
returnFormat,
) as EstimateFee;
}

/**
* Returns an estimate of the gas required for a L1 to L2 transaction.
*
* @param transaction - Transaction object.
* @param returnFormat - The format of the return value.
*/
public async estimateGasL1ToL2(
transaction: Partial<TransactionWithSenderAPI>,
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
Expand All @@ -133,6 +197,12 @@ export class RpcMethods {
) as Numbers;
}

/**
* Returns all balances for confirmed tokens given by an account address.
*
* @param address - The account address.
* @param returnFormat - The format of the return value.
*/
public async getAllAccountBalances(
address: Address,
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
Expand All @@ -152,6 +222,11 @@ export class RpcMethods {
return res;
}

/**
* Returns the address of the zkSync Era contract.
*
* @param returnFormat - The format of the return value.
*/
public async getMainContract(
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
): Promise<Address> {
Expand All @@ -162,17 +237,35 @@ export class RpcMethods {
) as Address;
}

/**
* Returns the range of blocks contained within a batch given by batch number.
* The range is given by beginning/end block numbers in hexadecimal.
*
* @param number The layer 1 batch number.
* @param returnFormat - The format of the return value.
*/
public async getL1BatchBlockRange(
number: number,
number: Numbers,
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
): Promise<Bytes[]> {
return format(
BytesArraySchema,
await this._send('zks_getL1BatchBlockRange', [number]),
await this._send('zks_getL1BatchBlockRange', [
typeof number === 'bigint' ? number.toString() : number,
]),
returnFormat,
) as Bytes[];
}

/**
* Returns Merkle proofs for one or more storage values at the specified account along with a Merkle proof of their authenticity. This allows to verify that the values have not been tampered with.
* More details: https://docs.zksync.io/build/api.html#zks-getproof
*
* @param address - The account to fetch storage values and proofs for.
* @param keys - Vector of storage keys in the account.
* @param l1BatchNumber - Number of the L1 batch specifying the point in time at which the requested values are returned.
* @param returnFormat - The format of the return value.
*/
public async getProof(
address: Address,
keys: string[],
Expand All @@ -196,6 +289,11 @@ export class RpcMethods {
return result;
}

/**
* Returns the address of the testnet paymaster: the paymaster that is available on testnets and enables paying fees in ERC-20 compatible tokens.
*
* @param returnFormat - The format of the return value.
*/
public async getTestnetPaymaster(
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
): Promise<Address> {
Expand All @@ -205,14 +303,26 @@ export class RpcMethods {
returnFormat,
) as Address;
}

/**
* Given a transaction hash, and an index of the L2 to L1 log produced within the transaction, it returns the proof for the corresponding L2 to L1 log.
*
* The index of the log that can be obtained from the transaction receipt (it includes a list of every log produced by the transaction)
*
* @param txHash - Hash of the L2 transaction the L2 to L1 log was produced within.
* @param l2ToL1LogIndex - The index of the L2 to L1 log in the transaction (optional).
* @param returnFormat - The format of the return value.
*/
public async getL2ToL1LogProof(
txHash: HexString32Bytes,
l2ToL1LogIndex?: number,
l2ToL1LogIndex?: Numbers,
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
): Promise<L2ToL1Proof> {
const params: [HexString32Bytes, number?] = [txHash];
if (l2ToL1LogIndex) {
params.push(l2ToL1LogIndex);
params.push(
typeof l2ToL1LogIndex === 'bigint' ? Number(l2ToL1LogIndex) : l2ToL1LogIndex,
);
}
return format(
L2ToL1ProofSchema,
Expand All @@ -221,6 +331,11 @@ export class RpcMethods {
) as L2ToL1Proof;
}

/**
* Returns L1/L2 addresses of default bridges.
*
* @param returnFormat - The format of the return value.
*/
public async getBridgeContracts(
returnFormat: DataFormat = DEFAULT_RETURN_FORMAT,
): Promise<BridgeAddresses> {
Expand Down

0 comments on commit b779027

Please sign in to comment.