From 25c3024a8937ada165573ebdd6eb28f44be2356f Mon Sep 17 00:00:00 2001 From: Richard Moore Date: Sat, 17 Apr 2021 22:09:50 -0400 Subject: [PATCH] docs: added AccessLists details (#1364). --- docs.wrm/api/contract/contract.wrm | 12 +-- docs.wrm/api/providers/types.wrm | 130 +++++++++++++++++++++++++++- docs.wrm/api/utils/transactions.wrm | 9 ++ docs.wrm/config.js | 2 + 4 files changed, 146 insertions(+), 7 deletions(-) diff --git a/docs.wrm/api/contract/contract.wrm b/docs.wrm/api/contract/contract.wrm index 76acfdf17a..7ecaec7cc3 100644 --- a/docs.wrm/api/contract/contract.wrm +++ b/docs.wrm/api/contract/contract.wrm @@ -8,15 +8,15 @@ to be run with the input of the transaction data. _subsection: Creating Instances @ -_property: new ethers.Contract(address, abi, signerOrProvider) @src +_property: new ethers.Contract(address, abi, signerOrProvider) @src -_property: contract.attach(addressOrName) => [[Contract]] @ @SRC +_property: contract.attach(addressOrName) => [[Contract]] @ @SRC Returns a new instance of the **Contract** attached to a new address. This is useful if there are multiple similar or identical copies of a Contract on the network and you wish to interact with each of them. -_property: contract.connect(providerOrSigner) => [[Contract]] @ @SRC +_property: contract.connect(providerOrSigner) => [[Contract]] @ @SRC Returns a new instance of the Contract, but connected to //providerOrSigner//. @@ -65,11 +65,11 @@ _subsection: Events @ _property: contract.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise> @ @SRC Return Events that match the //event//. -_property: contract.listenerCount([ event ]) => number @ @SRC +_property: contract.listenerCount([ event ]) => number @ @SRC Return the number of listeners that are subscribed to //event//. If no event is provided, returns the total count of all events. -_property: contract.listeners(event) => Array @ @SRC +_property: contract.listeners(event) => Array @ @SRC Return a list of listeners that are subscribed to //event//. _property: contract.off(event, listener) => this @ @SRC @@ -82,7 +82,7 @@ _property: contract.once(event, listener) => this @ @SRC this @ @SRC +_property: contract.removeAllListeners([ event ]) => this @ @SRC Unsubscribe all listeners for //event//. If no event is provided, all events are unsubscribed. diff --git a/docs.wrm/api/providers/types.wrm b/docs.wrm/api/providers/types.wrm index 29ad5d1378..73af4d64e5 100644 --- a/docs.wrm/api/providers/types.wrm +++ b/docs.wrm/api/providers/types.wrm @@ -202,7 +202,18 @@ The chain ID this transaction is authorized on, as specified by If the chain ID is 0 will disable EIP-155 and the transaction will be valid on any network. This can be **dangerous** and care should be taken, since it allows transactions to be replayed on networks that were possibly not -intended. +intended. Intentionally-replayable transactions are also disabled by default +on recent versions of Geth and require configuration to enable. + +_property: transactionRequest.type => null | number + +The [[link-eip-2718]] type of this transaction envelope, or ``null`` +for legacy transactions that do not have an envelope. + +_property: transactionRequest.accessList => [[providers-AccessListish]] + +The [[providers-AccessList]] to include in an [[link-eip-2930]] transaction, which will +include a ``type`` of ``1``. _heading: TransactionResponse @ @INHERIT<[[Transaction]]> @@ -241,6 +252,16 @@ the following properties: - ``error.transactionHash`` - the hash of the transaction - ``error.receipt`` - the actual receipt, with the status of ``0`` +_property: transactionRequest.type => null | number + +The [[link-eip-2718]] type of this transaction envelope, or ``null`` +for legacy transactions that do not have an envelope. + +_property: transactionRequest.accessList => [[providers-AccessList]] + +The [[providers-AccessList]] included in an [[link-eip-2930]] transaction, which will +also have its ``type`` equal to ``1``. + _heading: TransactionReceipt @ _property: receipt.to => string<[[address]]> @@ -314,3 +335,110 @@ _property: receipt.status => boolean The status of a transaction is 1 is successful or 0 if it was reverted. Only transactions included in blocks [post-Byzantium Hard Fork](link-eip-609) have this property. + +_subsection: Access Lists + +An Access List is optional an includes a list of addresses and storage +slots for that address which should be //warmed// or pre-fetched for +use within the execution of this transaction. A //warmed// value has an +additional upfront cost to access, but is discounted throughout the code +execution for reading and writing. + +_heading: AccessListish @ + +A looser description of an [[providers-AccessList]], which will be +converted internally using [accessListify](utils-accessListify). + + +It may be any of: + +- any [[providers-AccessList]] +- an Array of 2-element Arrays, where the first element is the address + and second array is an array of storage keys +- an object, whose keys represent the addresses and each value is an + array of storage keys + +When using the object form (the last option), the addresses and storage +slots will be sorted. If an explicit order for the access list is +required, one of the other forms must be used. Most developers +**do not** require explicit order. + +_code: equivalent to the AccessList example below @lang + +// Option 1: +// AccessList +// see below + +// Option 2: +// Array< [ Address, Array ] > +[ + [ + "0x0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e", + [ + "0x0000000000000000000000000000000000000000000000000000000000000004", + "0x0bcad17ecf260d6506c6b97768bdc2acfb6694445d27ffd3f9c1cfbee4a9bd6d" + ] + ], + [ + "0x5FfC014343cd971B7eb70732021E26C35B744cc4", + [ + "0x0000000000000000000000000000000000000000000000000000000000000001" + ] + ] +] +// +; +// + +// Option 3: +// Record> +// +( +// +{ + "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e": [ + "0x0000000000000000000000000000000000000000000000000000000000000004", + "0x0bcad17ecf260d6506c6b97768bdc2acfb6694445d27ffd3f9c1cfbee4a9bd6d" + ], + "0x5FfC014343cd971B7eb70732021E26C35B744cc4": [ + "0x0000000000000000000000000000000000000000000000000000000000000001" + ] +} +// +) +// + + +_heading: AccessList @ + +An [[link-eip-2930]] transaction allows an optional **AccessList** +which causes a transaction to //warm// (i.e. pre-cache) another +addresses state and the specified storage keys. + +This incurs an increased intrinsic cost for the transaction, but provides +discounts for storage and state access throughout the execution of the +transaction. + +_code: example access list + +// Array of objects with the form: +// { +// address: Address, +// storageKey: Array< DataHexString< 32 > > +// } + +[ + { + address: "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e", + storageKeys: [ + "0x0000000000000000000000000000000000000000000000000000000000000004", + "0x0bcad17ecf260d6506c6b97768bdc2acfb6694445d27ffd3f9c1cfbee4a9bd6d" + ] + }, + { + address: "0x5FfC014343cd971B7eb70732021E26C35B744cc4", + storageKeys: [ + "0x0000000000000000000000000000000000000000000000000000000000000001" + ] + } +] diff --git a/docs.wrm/api/utils/transactions.wrm b/docs.wrm/api/utils/transactions.wrm index 5aca013f35..76bd8830fc 100644 --- a/docs.wrm/api/utils/transactions.wrm +++ b/docs.wrm/api/utils/transactions.wrm @@ -97,6 +97,15 @@ used to encode the chain ID into the serialized transaction. _subsection: Functions @ +_property: ethers.utils.accessListify(anAcceslistish) => [[providers-AccessList]] @ @SRC +Normalizes the [[providers-AccessListish]] //anAccessListish// into +an [[providers-AccessList]]. + +This is useful for other utility functions which wish to remain +flexible as to the input parameter for access lists, such as +when creating a [[Signer]] which needs to manipulate a possibly +typed transaction envelope. + _property: ethers.utils.parseTransaction(aBytesLike) => [[Transaction]] @ @SRC Parses the transaction properties from a serialized transaction. diff --git a/docs.wrm/config.js b/docs.wrm/config.js index db2d2b8255..0b8a03ce81 100644 --- a/docs.wrm/config.js +++ b/docs.wrm/config.js @@ -260,6 +260,8 @@ module.exports = { "link-eip-1577": { name: "EIP-1577", url: "https:/\/eips.ethereum.org/EIPS/eip-1577" }, "link-eip-2098": { name: "EIP-2098", url: "https:/\/eips.ethereum.org/EIPS/eip-2098" }, "link-eip-2304": { name: "EIP-2304", url: "https:/\/eips.ethereum.org/EIPS/eip-2304" }, + "link-eip-2718": { name: "EIP-2718", url: "https:/\/eips.ethereum.org/EIPS/eip-2718" }, + "link-eip-2930": { name: "EIP-2930", url: "https:/\/eips.ethereum.org/EIPS/eip-2930" }, "link-bip-39": { name: "BIP-39", url: "https:/\/en.bitcoin.it/wiki/BIP_0039" }, "link-bip-32": { name: "BIP-32", url: "https:/\/github.com/bitcoin/bips/blob/master/bip-0032.mediawiki" }, "link-bip-44": { name: "BIP-44", url: "https:/\/en.bitcoin.it/wiki/BIP_0044" },