viem 0.3.17 → 0.3.19

package/src/utils/abi/encodeFunctionResult.ts

@@ -3,42 +3,63 @@ import type { Abi, Narrow } from 'abitype'
 import {
   AbiFunctionNotFoundError,
   AbiFunctionOutputsNotFoundError,
-} from '../../errors/index.js'
+} from '../../errors/abi.js'
 import type {
+  AbiItem,
   ContractFunctionResult,
   InferFunctionName,
-} from '../../types/index.js'
+} from '../../types/contract.js'
+
 import { encodeAbiParameters } from './encodeAbiParameters.js'
+import { type GetAbiItemParameters, getAbiItem } from './getAbiItem.js'
 
 const docsPath = '/docs/contract/encodeFunctionResult'
 
 export type EncodeFunctionResultParameters<
   TAbi extends Abi | readonly unknown[] = Abi,
-  TFunctionName extends string = string,
+  TFunctionName extends string | undefined = string,
+  _FunctionName = InferFunctionName<TAbi, TFunctionName>,
 > = {
-  abi: Narrow<TAbi>
-  functionName: InferFunctionName<TAbi, TFunctionName>
-  result?: ContractFunctionResult<TAbi, TFunctionName>
-}
+  functionName?: _FunctionName
+} & (TFunctionName extends string
+  ? { abi: Narrow<TAbi>; result?: ContractFunctionResult<TAbi, TFunctionName> }
+  : _FunctionName extends string
+  ? {
+      abi: [Narrow<TAbi[number]>]
+      result?: ContractFunctionResult<TAbi, _FunctionName>
+    }
+  : never)
 
 export function encodeFunctionResult<
   TAbi extends Abi | readonly unknown[],
-  TFunctionName extends string,
+  TFunctionName extends string | undefined = undefined,
 >({
   abi,
   functionName,
   result,
 }: EncodeFunctionResultParameters<TAbi, TFunctionName>) {
-  const description = (abi as Abi).find(
-    (x) => 'name' in x && x.name === functionName,
-  )
-  if (!description)
-    throw new AbiFunctionNotFoundError(functionName, { docsPath })
-  if (!('outputs' in description))
-    throw new AbiFunctionOutputsNotFoundError(functionName, { docsPath })
+  let abiItem = abi[0] as AbiItem
+  if (functionName) {
+    abiItem = getAbiItem({
+      abi,
+      name: functionName,
+    } as GetAbiItemParameters)
+    if (!abiItem)
+      throw new AbiFunctionNotFoundError(functionName, {
+        docsPath: '/docs/contract/encodeFunctionResult',
+      })
+  }
+
+  if (abiItem.type !== 'function')
+    throw new AbiFunctionNotFoundError(undefined, {
+      docsPath: '/docs/contract/encodeFunctionResult',
+    })
+
+  if (!abiItem.outputs)
+    throw new AbiFunctionOutputsNotFoundError(abiItem.name, { docsPath })
 
   let values = Array.isArray(result) ? result : [result]
-  if (description.outputs.length === 0 && !values[0]) values = []
+  if (abiItem.outputs.length === 0 && !values[0]) values = []
 
-  return encodeAbiParameters(description.outputs, values)
+  return encodeAbiParameters(abiItem.outputs, values)
 }

package/src/utils/abi/encodePacked.ts

@@ -1,6 +1,7 @@
 import type {
   AbiParameterToPrimitiveType,
   AbiType,
+  Address,
   Narrow,
   SolidityAddress,
   SolidityArrayWithoutTuple,
@@ -13,13 +14,14 @@ import type {
 import {
   AbiEncodingLengthMismatchError,
   BytesSizeMismatchError,
-  InvalidAddressError,
   UnsupportedPackedAbiType,
-} from '../../errors/index.js'
-import type { Address, Hex } from '../../types/index.js'
-import { isAddress } from '../address/index.js'
-import { concat, pad } from '../data/index.js'
-import { boolToHex, numberToHex, stringToHex } from '../encoding/index.js'
+} from '../../errors/abi.js'
+import { InvalidAddressError } from '../../errors/address.js'
+import type { Hex } from '../../types/misc.js'
+import { isAddress } from '../address/isAddress.js'
+import { concat } from '../data/concat.js'
+import { pad } from '../data/pad.js'
+import { boolToHex, numberToHex, stringToHex } from '../encoding/toHex.js'
 import { arrayRegex, bytesRegex, integerRegex } from '../regex.js'
 
 type PackedAbiType =

package/src/utils/abi/formatAbiItem.ts

@@ -1,7 +1,7 @@
 import type { AbiParameter } from 'abitype'
 
-import { InvalidDefinitionTypeError } from '../../errors/index.js'
-import type { AbiItem } from '../../types/index.js'
+import { InvalidDefinitionTypeError } from '../../errors/abi.js'
+import type { AbiItem } from '../../types/contract.js'
 
 export function formatAbiItem(
   abiItem: AbiItem,

package/src/utils/abi/formatAbiItemWithArgs.ts

@@ -1,7 +1,7 @@
 import type { AbiParameter } from 'abitype'
 
-import type { AbiItem } from '../../types/index.js'
-import { stringify } from '../index.js'
+import type { AbiItem } from '../../types/contract.js'
+import { stringify } from '../stringify.js'
 
 export function formatAbiItemWithArgs({
   abiItem,

package/src/utils/abi/getAbiItem.ts

@@ -1,7 +1,7 @@
 import type { Abi, AbiParameter, Address, Narrow } from 'abitype'
 
-import type { GetFunctionArgs, InferItemName } from '../../types/index.js'
-import { isAddress } from '../address/index.js'
+import type { GetFunctionArgs, InferItemName } from '../../types/contract.js'
+import { isAddress } from '../address/isAddress.js'
 
 export type GetAbiItemParameters<
   TAbi extends Abi | readonly unknown[] = Abi,

package/src/utils/address/getAddress.ts

@@ -1,7 +1,9 @@
-import { InvalidAddressError } from '../../errors/index.js'
-import type { Address } from '../../types/index.js'
-import { stringToBytes } from '../encoding/index.js'
-import { keccak256 } from '../hash/index.js'
+import type { Address } from 'abitype'
+
+import { InvalidAddressError } from '../../errors/address.js'
+import { stringToBytes } from '../encoding/toBytes.js'
+import { keccak256 } from '../hash/keccak256.js'
+
 import { isAddress } from './isAddress.js'
 
 export function checksumAddress(address_: Address, chainId?: number): Address {

package/src/utils/address/getContractAddress.ts

@@ -1,7 +1,14 @@
-import type { Address, ByteArray, Hex } from '../../types/index.js'
-import { concat, isBytes, pad, slice } from '../data/index.js'
-import { toBytes, toRlp } from '../encoding/index.js'
-import { keccak256 } from '../hash/index.js'
+import type { Address } from 'abitype'
+
+import type { ByteArray, Hex } from '../../types/misc.js'
+import { concat } from '../data/concat.js'
+import { isBytes } from '../data/isBytes.js'
+import { pad } from '../data/pad.js'
+import { slice } from '../data/slice.js'
+import { toBytes } from '../encoding/toBytes.js'
+import { toRlp } from '../encoding/toRlp.js'
+import { keccak256 } from '../hash/keccak256.js'
+
 import { getAddress } from './getAddress.js'
 
 export type GetCreateAddressOptions = {

package/src/utils/address/isAddress.ts

@@ -1,4 +1,4 @@
-import type { Address } from '../../types/index.js'
+import type { Address } from 'abitype'
 
 const addressRegex = /^0x[a-fA-F0-9]{40}$/
 

package/src/utils/address/isAddressEqual.ts

@@ -1,5 +1,7 @@
-import { InvalidAddressError } from '../../errors/index.js'
-import type { Address } from '../../types/index.js'
+import type { Address } from 'abitype'
+
+import { InvalidAddressError } from '../../errors/address.js'
+
 import { isAddress } from './isAddress.js'
 
 export function isAddressEqual(a: Address, b: Address) {

package/src/utils/buildRequest.ts

@@ -1,7 +1,7 @@
-import type { RpcError } from '../errors/index.js'
+import { BaseError } from '../errors/base.js'
+import { HttpRequestError } from '../errors/request.js'
 import {
-  BaseError,
-  HttpRequestError,
+  ChainDisconnectedError,
   InternalRpcError,
   InvalidInputRpcError,
   InvalidParamsRpcError,
@@ -11,20 +11,19 @@ import {
   MethodNotFoundRpcError,
   MethodNotSupportedRpcError,
   ParseRpcError,
+  ProviderDisconnectedError,
   ResourceNotFoundRpcError,
   ResourceUnavailableRpcError,
+  type RpcError,
   SwitchChainError,
   TransactionRejectedRpcError,
-  UnknownRpcError,
-  UserRejectedRequestError,
-} from '../errors/index.js'
-import {
-  ChainDisconnectedError,
-  ProviderDisconnectedError,
   UnauthorizedProviderError,
+  UnknownRpcError,
   UnsupportedProviderMethodError,
+  UserRejectedRequestError,
 } from '../errors/rpc.js'
-import { withRetry } from './promise/index.js'
+
+import { withRetry } from './promise/withRetry.js'
 
 export const isDeterministicError = (error: Error) => {
   if ('code' in error)

package/src/utils/ccip.ts

@@ -1,19 +1,25 @@
-import { call } from '../actions/public/call.js'
-import type { CallParameters } from '../actions/public/index.js'
-import type { PublicClient, Transport } from '../clients/index.js'
+import type { Abi, Address } from 'abitype'
+
+import { type CallParameters, call } from '../actions/public/call.js'
+import type { PublicClient } from '../clients/createPublicClient.js'
+import type { Transport } from '../clients/transports/createTransport.js'
+import { type BaseError } from '../errors/base.js'
 import {
-  BaseError,
-  HttpRequestError,
   OffchainLookupError,
   OffchainLookupResponseMalformedError,
   OffchainLookupSenderMismatchError,
-} from '../errors/index.js'
-import type { Chain, GetErrorArgs, Hex } from '../types/index.js'
-import { decodeErrorResult, encodeAbiParameters } from './abi/index.js'
-import { isAddressEqual } from './address/index.js'
-import { concat, isHex } from './data/index.js'
+} from '../errors/ccip.js'
+import { HttpRequestError } from '../errors/request.js'
+import type { Chain } from '../types/chain.js'
+import type { GetErrorArgs } from '../types/contract.js'
+import type { Hex } from '../types/misc.js'
+
+import { decodeErrorResult } from './abi/decodeErrorResult.js'
+import { encodeAbiParameters } from './abi/encodeAbiParameters.js'
+import { isAddressEqual } from './address/isAddressEqual.js'
+import { concat } from './data/concat.js'
+import { isHex } from './data/isHex.js'
 import { stringify } from './stringify.js'
-import type { Abi, Address } from 'abitype'
 
 export const offchainLookupSignature = '0x556f1830'
 export const offchainLookupAbiItem = {

package/src/utils/chain.ts

@@ -1,5 +1,6 @@
-import { ChainDoesNotSupportContract } from '../errors/index.js'
-import type { Chain, ChainContract, Formatters } from '../types/index.js'
+import { ChainDoesNotSupportContract } from '../errors/chain.js'
+import type { Chain, ChainContract } from '../types/chain.js'
+import type { Formatters } from '../types/formatter.js'
 
 export function defineChain<
   TFormatters extends Formatters = Formatters,

package/src/utils/data/concat.ts

@@ -1,4 +1,4 @@
-import type { ByteArray, Hex } from '../../types/index.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
 
 export type ConcatReturnType<TValue extends Hex | ByteArray> =
   TValue extends Hex ? Hex : ByteArray

package/src/utils/data/isBytes.ts

@@ -1,4 +1,4 @@
-import type { ByteArray } from '../../types/index.js'
+import type { ByteArray } from '../../types/misc.js'
 
 export function isBytes(value: unknown): value is ByteArray {
   if (!value) return false

package/src/utils/data/isBytesEqual.ts

@@ -0,0 +1,8 @@
+import { type ByteArray, type Hex, isHex, toBytes } from '../../index.js'
+import { equalBytes } from '@noble/curves/abstract/utils'
+
+export function isBytesEqual(a_: ByteArray | Hex, b_: ByteArray | Hex) {
+  const a = isHex(a_) ? toBytes(a_) : a_
+  const b = isHex(b_) ? toBytes(b_) : b_
+  return equalBytes(a, b)
+}

package/src/utils/data/isHex.ts

@@ -1,4 +1,4 @@
-import type { Hex } from '../../types/index.js'
+import type { Hex } from '../../types/misc.js'
 
 export function isHex(value: unknown): value is Hex {
   if (!value) return false

package/src/utils/data/pad.ts

@@ -1,5 +1,5 @@
-import { SizeExceedsPaddingSizeError } from '../../errors/index.js'
-import type { ByteArray, Hex } from '../../types/index.js'
+import { SizeExceedsPaddingSizeError } from '../../errors/data.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
 
 type PadOptions = {
   dir?: 'left' | 'right'

package/src/utils/data/size.ts

@@ -1,4 +1,5 @@
-import type { ByteArray, Hex } from '../../types/index.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
+
 import { isHex } from './isHex.js'
 
 /**

package/src/utils/data/slice.ts

@@ -1,5 +1,6 @@
 import { SliceOffsetOutOfBoundsError } from '../../errors/data.js'
-import type { ByteArray, Hex } from '../../types/index.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
+
 import { isHex } from './isHex.js'
 import { size } from './size.js'
 

package/src/utils/data/trim.ts

@@ -1,4 +1,4 @@
-import type { ByteArray, Hex } from '../../types/index.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
 
 type TrimOptions = {
   dir?: 'left' | 'right'

package/src/utils/encoding/fromBytes.ts

@@ -1,6 +1,7 @@
-import { InvalidBytesBooleanError } from '../../errors/index.js'
-import type { ByteArray, Hex } from '../../types/index.js'
+import { InvalidBytesBooleanError } from '../../errors/encoding.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
 import { trim } from '../data/trim.js'
+
 import { assertSize, hexToBigInt, hexToNumber } from './fromHex.js'
 import { bytesToHex } from './toHex.js'
 
@@ -133,8 +134,6 @@ export function bytesToBool(
   return Boolean(bytes[0])
 }
 
-export { bytesToHex }
-
 export type BytesToNumberOpts = BytesToBigIntOpts
 
 /**

package/src/utils/encoding/fromHex.ts

@@ -1,10 +1,11 @@
 import {
   InvalidHexBooleanError,
   SizeOverflowError,
-} from '../../errors/index.js'
-import type { ByteArray, Hex } from '../../types/index.js'
-import { trim } from '../data/index.js'
+} from '../../errors/encoding.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
 import { size as size_ } from '../data/size.js'
+import { trim } from '../data/trim.js'
+
 import { hexToBytes } from './toBytes.js'
 
 export function assertSize(

package/src/utils/encoding/fromRlp.ts

@@ -3,8 +3,9 @@ import {
   DataLengthTooShortError,
   InvalidHexValueError,
   OffsetOutOfBoundsError,
-} from '../../errors/index.js'
-import type { ByteArray, Hex } from '../../types/index.js'
+} from '../../errors/encoding.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
+
 import { bytesToNumber } from './fromBytes.js'
 import { hexToBytes } from './toBytes.js'
 import { bytesToHex } from './toHex.js'

package/src/utils/encoding/toBytes.ts

@@ -1,10 +1,10 @@
-import { BaseError } from '../../errors/index.js'
-import type { ByteArray, Hex } from '../../types/index.js'
+import { BaseError } from '../../errors/base.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
 import { isHex } from '../data/isHex.js'
 import { pad } from '../data/pad.js'
+
 import { assertSize } from './fromHex.js'
-import type { NumberToHexOpts } from './toHex.js'
-import { numberToHex } from './toHex.js'
+import { type NumberToHexOpts, numberToHex } from './toHex.js'
 
 const encoder = new TextEncoder()
 

package/src/utils/encoding/toHex.ts

@@ -1,6 +1,7 @@
-import { IntegerOutOfRangeError } from '../../errors/index.js'
-import type { ByteArray, Hex } from '../../types/index.js'
-import { pad } from '../data/index.js'
+import { IntegerOutOfRangeError } from '../../errors/encoding.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
+import { pad } from '../data/pad.js'
+
 import { assertSize } from './fromHex.js'
 
 const hexes = Array.from({ length: 256 }, (_v, i) =>

package/src/utils/encoding/toRlp.ts

@@ -1,5 +1,6 @@
-import type { ByteArray, Hex } from '../../types/index.js'
-import { concat } from '../data/index.js'
+import type { ByteArray, Hex } from '../../types/misc.js'
+import { concat } from '../data/concat.js'
+
 import { toBytes } from './toBytes.js'
 import { bytesToHex } from './toHex.js'
 

package/src/utils/ens/avatar/parseAvatarRecord.ts

@@ -1,5 +1,8 @@
-import type { PublicClient, Transport } from '../../../clients/index.js'
-import type { AssetGatewayUrls, Chain } from '../../../types/index.js'
+import type { PublicClient } from '../../../clients/createPublicClient.js'
+import type { Transport } from '../../../clients/transports/createTransport.js'
+import type { Chain } from '../../../types/chain.js'
+import type { AssetGatewayUrls } from '../../../types/ens.js'
+
 import {
   getJsonImage,
   getMetadataAvatarUri,

package/src/utils/ens/avatar/utils.ts

@@ -1,12 +1,16 @@
-import { readContract } from '../../../actions/index.js'
-import type { PublicClient, Transport } from '../../../clients/index.js'
+import type { Address } from 'abitype'
+
+import { readContract } from '../../../actions/public/readContract.js'
+import type { PublicClient } from '../../../clients/createPublicClient.js'
+import type { Transport } from '../../../clients/transports/createTransport.js'
 import {
   EnsAvatarInvalidMetadataError,
   EnsAvatarInvalidNftUriError,
   EnsAvatarUnsupportedNamespaceError,
   EnsAvatarUriResolutionError,
-} from '../../../errors/index.js'
-import type { Address, AssetGatewayUrls, Chain } from '../../../types/index.js'
+} from '../../../errors/ens.js'
+import type { Chain } from '../../../types/chain.js'
+import type { AssetGatewayUrls } from '../../../types/ens.js'
 
 type UriItem = {
   uri: string

package/src/utils/ens/labelhash.ts

@@ -1,5 +1,6 @@
-import { bytesToHex, stringToBytes } from '../encoding/index.js'
-import { keccak256 } from '../hash/index.js'
+import { stringToBytes } from '../encoding/toBytes.js'
+import { bytesToHex } from '../encoding/toHex.js'
+import { keccak256 } from '../hash/keccak256.js'
 
 /**
  * @description Hashes ENS label

package/src/utils/ens/namehash.ts

@@ -1,6 +1,7 @@
-import { concat } from '../data/index.js'
-import { bytesToHex, stringToBytes } from '../encoding/index.js'
-import { keccak256 } from '../hash/index.js'
+import { concat } from '../data/concat.js'
+import { stringToBytes } from '../encoding/toBytes.js'
+import { bytesToHex } from '../encoding/toHex.js'
+import { keccak256 } from '../hash/keccak256.js'
 
 /**
  * @description Hashes ENS name

package/src/utils/ens/packetToBytes.ts

@@ -1,6 +1,6 @@
 // Adapted from https://github.com/mafintosh/dns-packet
-import type { ByteArray } from '../../types/index.js'
-import { stringToBytes } from '../encoding/index.js'
+import type { ByteArray } from '../../types/misc.js'
+import { stringToBytes } from '../encoding/toBytes.js'
 
 /*
  * @description Encodes a DNS packet into a ByteArray containing a UDP payload.

package/src/utils/errors/getCallError.ts

@@ -1,7 +1,8 @@
-import type { CallParameters } from '../../actions/index.js'
-import type { BaseError } from '../../errors/index.js'
-import { CallExecutionError } from '../../errors/index.js'
-import type { Chain } from '../../types/index.js'
+import type { CallParameters } from '../../actions/public/call.js'
+import type { BaseError } from '../../errors/base.js'
+import { CallExecutionError } from '../../errors/contract.js'
+import type { Chain } from '../../types/chain.js'
+
 import { containsNodeError, getNodeError } from './getNodeError.js'
 
 export function getCallError(

package/src/utils/errors/getContractError.ts

@@ -1,16 +1,13 @@
-import type { Abi } from 'abitype'
+import type { Abi, Address } from 'abitype'
 
+import { AbiDecodingZeroDataError } from '../../errors/abi.js'
+import { BaseError } from '../../errors/base.js'
 import {
+  ContractFunctionExecutionError,
   ContractFunctionRevertedError,
   ContractFunctionZeroDataError,
-} from '../../errors/contract.js'
-import { BaseError } from '../../errors/index.js'
-import {
-  AbiDecodingZeroDataError,
-  ContractFunctionExecutionError,
   RawContractError,
-} from '../../errors/index.js'
-import type { Address } from '../../types/index.js'
+} from '../../errors/contract.js'
 
 const EXECUTION_REVERTED_ERROR_CODE = 3
 

package/src/utils/errors/getEstimateGasError.ts

@@ -1,7 +1,9 @@
-import type { EstimateGasParameters } from '../../actions/index.js'
-import type { BaseError } from '../../errors/index.js'
-import { EstimateGasExecutionError } from '../../errors/index.js'
-import type { Account, Chain } from '../../types/index.js'
+import type { Account } from '../../accounts/types.js'
+import type { EstimateGasParameters } from '../../actions/public/estimateGas.js'
+import type { BaseError } from '../../errors/base.js'
+import { EstimateGasExecutionError } from '../../errors/estimateGas.js'
+import type { Chain } from '../../types/chain.js'
+
 import { containsNodeError, getNodeError } from './getNodeError.js'
 
 export function getEstimateGasError(

package/src/utils/errors/getNodeError.ts

@@ -1,5 +1,5 @@
-import type { SendTransactionParameters } from '../../actions/index.js'
-import { type BaseError, RpcRequestError } from '../../errors/index.js'
+import type { SendTransactionParameters } from '../../actions/wallet/sendTransaction.js'
+import type { BaseError } from '../../errors/base.js'
 import {
   ExecutionRevertedError,
   FeeCapTooHighError,
@@ -7,15 +7,18 @@ import {
   InsufficientFundsError,
   IntrinsicGasTooHighError,
   IntrinsicGasTooLowError,
-  InvalidInputRpcError,
   NonceMaxValueError,
   NonceTooHighError,
   NonceTooLowError,
   TipAboveFeeCapError,
-  TransactionRejectedRpcError,
   TransactionTypeNotSupportedError,
   UnknownNodeError,
-} from '../../errors/index.js'
+} from '../../errors/node.js'
+import { RpcRequestError } from '../../errors/request.js'
+import {
+  InvalidInputRpcError,
+  TransactionRejectedRpcError,
+} from '../../errors/rpc.js'
 
 export function containsNodeError(err: BaseError) {
   return (

package/src/utils/errors/getTransactionError.ts

@@ -1,7 +1,9 @@
-import type { BaseError } from '../../errors/index.js'
-import { TransactionExecutionError } from '../../errors/index.js'
-import type { Account, Chain } from '../../types/index.js'
-import type { SendTransactionParameters } from '../../wallet.js'
+import type { Account } from '../../accounts/types.js'
+import type { SendTransactionParameters } from '../../actions/wallet/sendTransaction.js'
+import type { BaseError } from '../../errors/base.js'
+import { TransactionExecutionError } from '../../errors/transaction.js'
+import type { Chain } from '../../types/chain.js'
+
 import { containsNodeError, getNodeError } from './getNodeError.js'
 
 export function getTransactionError(

package/src/utils/filters/createFilterRequestScope.ts

@@ -1,8 +1,9 @@
-import type { Chain } from '../../chains.js'
-import type { PublicClient, Transport } from '../../clients/index.js'
+import type { PublicClient } from '../../clients/createPublicClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
 import type { OnResponseFn } from '../../clients/transports/fallback.js'
+import type { Chain } from '../../types/chain.js'
 import type { Requests } from '../../types/eip1193.js'
-import type { Hex } from '../../types/index.js'
+import type { Hex } from '../../types/misc.js'
 
 type CreateFilterRequestScopeParameters = {
   method: