ethers.js/docs.wrm/api/utils/abi/fragments.wrm

250 lines
9.6 KiB
Plaintext
Raw Normal View History

2020-05-08 10:24:40 +03:00
_section: Fragments @<fragments>
2020-01-10 09:01:00 +03:00
Explain an ABI.
_subsection: Formats
_heading: JSON String ABI (Solidity Output JSON)
The **JSON ABI Format** is the format that is
2020-02-02 15:58:29 +03:00
[output from the Solidity compiler](link-solc-output).
2020-01-10 09:01:00 +03:00
A JSON serialized object is always a string, which represents an Array
2020-05-08 10:24:40 +03:00
of Objects, where each Object has various properties describing the [[Fragment]] of the ABI.
2020-01-10 09:01:00 +03:00
The deserialized JSON string (which is a normal JavaScript Object) may
2020-01-10 09:01:00 +03:00
also be passed into any function which accepts a JSON String ABI.
_heading: Humanb-Readable ABI @<human-readable-abi>
The Human-Readable ABI was introduced by ethers in [this article](link-ricmoo-humanreadableabi)
and has since gained wider adoption.
2020-01-10 09:01:00 +03:00
The ABI is described by using an array of strings, where each string is the
Solidity signature of the **constructor**, **function**, **event** or **error**.
2020-01-10 09:01:00 +03:00
When parsing a fragment, all inferred properties will be injected (e.g. a //payable//
method will have its ``constant`` proeprty set to false).
2020-01-10 09:01:00 +03:00
Tuples can be specified by using the ``tuple(...)`` syntax or with bare (additional)
parenthesis, ``(...)``.
2020-02-25 22:57:11 +03:00
_code: Example Human-Readable ABI
const ABI = [
// Constructor
"constructor(address ens)",
// Constant functions (pure or view)
"function balanceOf(address owner) view returns (uint)",
// State-mutating functions (payable or non-payable)
"function mint(uint amount) payable",
"function transfer(address to, uint amount) returns (bool)",
// Events
"event Transfer(address indexed from, address indexed to, uint amount)",
// Errors
"error InsufficientFunds(address from, uint balance)",
]
2020-01-10 09:01:00 +03:00
_heading: Output Formats @<fragments--output-formats> @SRC<abi/fragments:FormatTypes>
2020-05-08 10:24:40 +03:00
Each [[Fragment]] and [[ParamType]] may be output using its ``format``
2020-01-10 09:01:00 +03:00
method.
2021-06-24 06:40:50 +03:00
_property: ethers.utils.FormatTypes.full => string
2020-01-10 09:01:00 +03:00
This is a full human-readable string, including all parameter names, any
optional modifiers (e.g. ``indexed``, ``public``, etc) and white-space
2020-11-23 07:03:50 +03:00
to aid in human readability.
2020-01-10 09:01:00 +03:00
2021-06-24 06:40:50 +03:00
_property: ethers.utils.FormatTypes.minimal => string
2020-01-10 09:01:00 +03:00
This is similar to ``full``, except with no unnecessary whitespace or parameter
names. This is useful for storing a minimal string which can still fully
2020-05-08 10:24:40 +03:00
reconstruct the original Fragment using [Fragment&thinsp;.&thinsp;from](Fragment-from).
2020-01-10 09:01:00 +03:00
2021-06-24 06:40:50 +03:00
_property: ethers.utils.FormatTypes.json => string
2020-01-10 09:01:00 +03:00
This returns a JavaScript Object which is safe to call ``JSON.stringify``
on to create a JSON string.
2021-06-24 06:40:50 +03:00
_property: ethers.utils.FormatTypes.sighash => string
2020-01-10 09:01:00 +03:00
This is a minimal output format, which is used by Solidity when computing a
signature hash or an event topic hash.
_warning: Note
2020-05-08 10:24:40 +03:00
The ``sighash`` format is **insufficient** to re-create the original [[Fragment]],
2020-01-10 09:01:00 +03:00
since it discards modifiers such as indexed, anonymous, stateMutability, etc.
2021-06-24 06:40:50 +03:00
It is only useful for computing the selector for a Fragment, and cannot
be used to format an Interface.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_subsection: Fragment @<Fragment> @SRC<abi/fragments:class.Fragment>
2020-01-10 09:01:00 +03:00
An ABI is a collection of **Fragments**, where each fragment specifies:
2021-06-12 00:13:46 +03:00
- An [Error](ErrorFragment)
2020-05-08 10:24:40 +03:00
- An [Event](EventFragment)
- A [Function](FunctionFragment)
- A [Constructor](ConstructorFragment)
2020-01-10 09:01:00 +03:00
_heading: Properties
_property: fragment.name => string
This is the name of the Event or Function. This will be null for
2020-05-08 10:24:40 +03:00
a [[ConstructorFragment]].
2020-01-10 09:01:00 +03:00
_property: fragment.type => string
2020-05-08 10:24:40 +03:00
This is a string which indicates the type of the [[Fragment]]. This
2020-01-10 09:01:00 +03:00
will be one of:
- ``constructor``
- ``event``
- ``function``
2020-05-08 10:24:40 +03:00
_property: fragment.inputs => Array<[[ParamType]]>
2020-11-23 07:03:50 +03:00
This is an array of each [[ParamType]] for the input parameters to
2020-01-10 09:01:00 +03:00
the Constructor, Event of Function.
_heading: Methods
_property: fragment.format([ format = sighash]) => string @<Fragment-format> @SRC<abi/fragments:Fragment.format>
Creates a string representation of the Fragment using the available
[output formats](fragments--output-formats).
2020-01-10 09:01:00 +03:00
_property: ethers.utils.Fragment.from(objectOrString) => [[Fragment]] @<Fragment-from> @SRC<abi/fragments:Fragment.from>
Creates a new **Fragment** sub-class from any compatible //objectOrString//.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_property: ethers.utils.Fragment.isFragment(object) => boolean @<Fragment-isFragment> @SRC<abi/fragments:Fragment.isFragment>
Returns true if //object// is a **Fragment**.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_subsection: ConstructorFragment @<ConstructorFragment> @INHERIT<[[Fragment]]> @SRC<abi/fragments:class.ConstructorFragment>
2020-01-10 09:01:00 +03:00
_heading: Properties
2020-05-08 10:24:40 +03:00
_property: fragment.gas => [[BigNumber]]
2020-01-10 09:01:00 +03:00
This is the gas limit that should be used during deployment. It may be
null.
_property: fragment.payable => boolean
This is whether the constructor may receive ether during deployment as
an endowment (i.e. msg.value != 0).
_property: fragment.stateMutability => string
This is the state mutability of the constructor. It can be any of:
- ``nonpayable``
- ``payable``
_heading: Methods
2020-05-08 10:24:40 +03:00
_property: ethers.utils.ConstructorFragment.from(objectOrString) => [[ConstructorFragment]] @<ConstructorFragment-from> @SRC<abi/fragments:ConstructorFragment.from>
Creates a new **ConstructorFragment** from any compatible //objectOrString//.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_property: ethers.utils.ConstructorFragment.isConstructorFragment(object) => boolean @<ConstructorFragment-isConstructorFragment> @SRC<abi/fragments:ConstructorFragment.isConstructorFragment>
Returns true if //object// is a **ConstructorFragment**.
2020-01-10 09:01:00 +03:00
_subsection: ErrorFragment @<ErrorFragment> @INHERIT<[[Fragment]]> @SRC<abi/fragments:class.ErrorFragment>
_heading: Methods
_property: ethers.utils.ErrorFragment.from(objectOrString) => [[ErrorFragment]] @<ErrorFragment-from> @SRC<abi/fragments:ErrorFragment.from>
Creates a new **ErrorFragment** from any compatible //objectOrString//.
_property: ethers.utils.ErrorFragment.isErrorFragment(object) => boolean @<ErrorFragment-isErrorFragment> @SRC<abi/fragments:ErrorFragment.isErrorFragment>
Returns true if //object// is an **ErrorFragment**.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_subsection: EventFragment @<EventFragment> @INHERIT<[[Fragment]]> @SRC<abi/fragments:class.EventFragment>
2020-01-10 09:01:00 +03:00
_heading: Properties
_property: fragment.anonymous => boolean
This is whether the event is anonymous. An anonymous Event does not inject its
topic hash as topic0 when creating a log.
_heading: Methods
2020-05-08 10:24:40 +03:00
_property: ethers.utils.EventFragment.from(objectOrString) => [[EventFragment]] @<EventFragment-from> @SRC<abi/fragments:EventFragment.from>
Creates a new **EventFragment** from any compatible //objectOrString//.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_property: ethers.utils.EventFragment.isEventFragment(object) => boolean @<EventFragment-isEventFragment> @SRC<abi/fragments:EventFragment.isEventFragment>
Returns true if //object// is an **EventFragment**.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_subsection: FunctionFragment @<FunctionFragment> @INHERIT<[[ConstructorFragment]]> @SRC<abi/fragments:class.FunctionFragment>
2020-01-10 09:01:00 +03:00
_heading: Properties
_property: fragment.constant => boolean
This is whether the function is constant (i.e. does not change state). This
is true if the state mutability is ``pure`` or ``view``.
_property: fragment.stateMutability => string
This is the state mutability of the constructor. It can be any of:
- ``nonpayable``
- ``payable``
- ``pure``
- ``view``
2020-05-08 10:24:40 +03:00
_property: fragment.outputs => Array<[[ParamType]]>
2020-01-10 09:01:00 +03:00
A list of the Function output parameters.
_heading: Methods
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_property: ethers.utils.FunctionFragment.from(objectOrString) => [[FunctionFragment]] @<FunctionFragment-from> @SRC<abi/fragments:ConstructorFragment.from>
Creates a new **FunctionFragment** from any compatible //objectOrString//.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_property: ethers.utils.FunctionFragment.isFunctionFragment(object) => boolean @<FunctionFragment-isFunctionFragment> @SRC<abi/fragments:FunctionFragment.isFunctionFragment>
Returns true if //object// is a **FunctionFragment**.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_subsection: ParamType @<ParamType> @SRC<abi/fragments:class.ParamType>
2020-01-10 09:01:00 +03:00
The following examples will represent the Solidity parameter:
``string foobar``
_heading: Properties
2020-05-08 10:24:40 +03:00
_property: paramType.name => string @<ParamType-name>
2020-01-10 09:01:00 +03:00
The local parameter name. This may be null for unnamed parameters. For example,
the parameter definition ``string foobar`` would be ``foobar``.
2020-05-08 10:24:40 +03:00
_property: paramType.type => string @<ParamType-type>
2020-01-10 09:01:00 +03:00
The full type of the parameter, including tuple and array symbols. This may be null
for unnamed parameters. For the above example, this would be ``foobar``.
2020-05-08 10:24:40 +03:00
_property: paramType.baseType => string @<ParamType-baseType>
2020-01-10 09:01:00 +03:00
The base type of the parameter. For primitive types (e.g. ``address``, ``uint256``, etc)
2020-05-08 10:24:40 +03:00
this is equal to [type](ParamType-type). For arrays, it will be the string ``array`` and for
2020-01-10 09:01:00 +03:00
a tuple, it will be the string ``tuple``.
2020-05-08 10:24:40 +03:00
_property: paramType.indexed => boolean @<ParamType-indexed>
2020-01-10 09:01:00 +03:00
Whether the parameter has been marked as indexed. This **only** applies
2020-05-08 10:24:40 +03:00
to parameters which are part of an [[EventFragment]].
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_property: paramType.arrayChildren => [[ParamType]] @<ParamType-arrayChildren>
2020-11-23 07:03:50 +03:00
The type of children of the array. This is null for any parameter
2020-10-03 19:30:15 +03:00
which is not an array.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_property: paramType.arrayLength => number @<ParamType-arrayLength>
2020-01-10 09:01:00 +03:00
The length of the array, or ``-1`` for dynamic-length arrays. This is
2020-11-23 07:03:50 +03:00
null for parameters which are not arrays.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_property: paramType.components => Array<[[ParamType]]> @<ParamType-components>
2020-01-10 09:01:00 +03:00
The components of a tuple. This is null for non-tuple parameters.
_heading: Methods
2020-02-25 22:57:11 +03:00
_property: paramType.format([ outputType = sighash ])
Creates a string representation of the Fragment using the available
[output formats](fragments--output-formats).
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_property: ethers.utils.ParamType.from(objectOrString) => [[ParamType]] @<ParamType-from> @SRC<abi/fragments:ParamType.from>
Creates a new **ParamType** from any compatible //objectOrString//.
2020-01-10 09:01:00 +03:00
2020-05-08 10:24:40 +03:00
_property: ethers.utils.ParamType.isParamType(object) => boolean @<ParamType-isParamType> @SRC<abi/fragments:ParamType.isParamType>
Returns true if //object// is a **ParamType**.