viem 0.0.0-tsc-and-nodenext-20230405154910 → 0.0.0-w-20230711200108

package/src/chains/serializers/celo.ts

@@ -0,0 +1,190 @@
+import type { Address } from 'abitype'
+
+import { InvalidAddressError } from '../../errors/address.js'
+import { BaseError } from '../../errors/base.js'
+import { InvalidChainIdError } from '../../errors/chain.js'
+import { FeeCapTooHighError, TipAboveFeeCapError } from '../../errors/node.js'
+import type { FeeValuesEIP1559 } from '../../types/fee.js'
+import type { Signature } from '../../types/misc.js'
+import type { Serializers } from '../../types/serializer.js'
+import type {
+  AccessList,
+  TransactionSerializable,
+  TransactionSerializableBase,
+} from '../../types/transaction.js'
+import { isAddress } from '../../utils/address/isAddress.js'
+import { concatHex } from '../../utils/data/concat.js'
+import { trim } from '../../utils/data/trim.js'
+import { toHex } from '../../utils/encoding/toHex.js'
+import { toRlp } from '../../utils/encoding/toRlp.js'
+import { serializeAccessList } from '../../utils/transaction/serializeAccessList.js'
+import {
+  type SerializeTransactionFn,
+  serializeTransaction,
+} from '../../utils/transaction/serializeTransaction.js'
+
+export const serializeTransactionCelo: SerializeTransactionFn<
+  TransactionSerializableCelo
+> = (tx, signature) => {
+  // Handle CIP-42 transactions
+  if (isCIP42(tx))
+    return serializeTransactionCIP42(
+      tx as TransactionSerializableCIP42,
+      signature,
+    )
+
+  // Handle other transaction types
+  return serializeTransaction(tx as TransactionSerializable, signature)
+}
+
+export const serializersCelo = {
+  transaction: serializeTransactionCelo,
+} as const satisfies Serializers
+
+//////////////////////////////////////////////////////////////////////////////
+// Types
+
+export type TransactionSerializableCIP42<
+  TQuantity = bigint,
+  TIndex = number,
+> = TransactionSerializableBase<TQuantity, TIndex> &
+  FeeValuesEIP1559<TQuantity> & {
+    accessList?: AccessList
+    gasPrice?: never
+    feeCurrency?: Address
+    gatewayFeeRecipient?: Address
+    gatewayFee?: TQuantity
+    chainId: number
+    type?: 'cip42'
+  }
+
+export type TransactionSerializableCelo =
+  | TransactionSerializableCIP42
+  | TransactionSerializable
+
+export type SerializedCIP42TransactionReturnType = `0x7c${string}`
+
+//////////////////////////////////////////////////////////////////////////////
+// Serializers
+
+// There shall be a typed transaction with the code 0x7c that has the following format:
+// 0x7c || rlp([chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, feecurrency, gatewayFeeRecipient, gatewayfee, destination, amount, data, access_list, signature_y_parity, signature_r, signature_s]).
+// This will be in addition to the type 0x02 transaction as specified in EIP-1559.
+function serializeTransactionCIP42(
+  transaction: TransactionSerializableCIP42,
+  signature?: Signature,
+): SerializedCIP42TransactionReturnType {
+  assertTransactionCIP42(transaction)
+  const {
+    chainId,
+    gas,
+    nonce,
+    to,
+    value,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    accessList,
+    feeCurrency,
+    gatewayFeeRecipient,
+    gatewayFee,
+    data,
+  } = transaction
+
+  const serializedTransaction = [
+    toHex(chainId),
+    nonce ? toHex(nonce) : '0x',
+    maxPriorityFeePerGas ? toHex(maxPriorityFeePerGas) : '0x',
+    maxFeePerGas ? toHex(maxFeePerGas) : '0x',
+    gas ? toHex(gas) : '0x',
+    feeCurrency ?? '0x',
+    gatewayFeeRecipient ?? '0x',
+    gatewayFee ? toHex(gatewayFee) : '0x',
+    to ?? '0x',
+    value ? toHex(value) : '0x',
+    data ?? '0x',
+    serializeAccessList(accessList),
+  ]
+
+  if (signature) {
+    serializedTransaction.push(
+      signature.v === 27n ? '0x' : toHex(1), // yParity
+      trim(signature.r),
+      trim(signature.s),
+    )
+  }
+
+  return concatHex([
+    '0x7c',
+    toRlp(serializedTransaction),
+  ]) as SerializedCIP42TransactionReturnType
+}
+
+//////////////////////////////////////////////////////////////////////////////
+// Utilities
+
+// process as CIP42 if any of these fields are present. realistically gatewayfee is not used but is part of spec
+function isCIP42(transaction: TransactionSerializableCelo) {
+  if (
+    'maxFeePerGas' in transaction &&
+    'maxPriorityFeePerGas' in transaction &&
+    ('feeCurrency' in transaction ||
+      'gatewayFee' in transaction ||
+      'gatewayFeeRecipient' in transaction)
+  )
+    return true
+  return false
+}
+
+// maxFeePerGas must be less than 2^256 - 1: however writing like that caused exceptions to be raised
+const MAX_MAX_FEE_PER_GAS =
+  115792089237316195423570985008687907853269984665640564039457584007913129639935n
+
+function assertTransactionCIP42(transaction: TransactionSerializableCIP42) {
+  const {
+    chainId,
+    maxPriorityFeePerGas,
+    gasPrice,
+    maxFeePerGas,
+    to,
+    feeCurrency,
+    gatewayFee,
+    gatewayFeeRecipient,
+  } = transaction
+  if (chainId <= 0) throw new InvalidChainIdError({ chainId })
+  if (to && !isAddress(to)) throw new InvalidAddressError({ address: to })
+  if (gasPrice)
+    throw new BaseError(
+      '`gasPrice` is not a valid CIP-42 Transaction attribute.',
+    )
+
+  if (maxFeePerGas && maxFeePerGas > MAX_MAX_FEE_PER_GAS)
+    throw new FeeCapTooHighError({ maxFeePerGas })
+
+  if (
+    maxPriorityFeePerGas &&
+    maxFeePerGas &&
+    maxPriorityFeePerGas > maxFeePerGas
+  )
+    throw new TipAboveFeeCapError({ maxFeePerGas, maxPriorityFeePerGas })
+
+  if (
+    (gatewayFee && !gatewayFeeRecipient) ||
+    (gatewayFeeRecipient && !gatewayFee)
+  ) {
+    throw new BaseError(
+      '`gatewayFee` and `gatewayFeeRecipient` must be provided together.',
+    )
+  }
+
+  if (feeCurrency && !feeCurrency?.startsWith('0x')) {
+    throw new BaseError(
+      '`feeCurrency` MUST be a token address for CIP-42 transactions.',
+    )
+  }
+
+  if (!feeCurrency && !gatewayFeeRecipient) {
+    throw new BaseError(
+      'Either `feeCurrency` or `gatewayFeeRecipient` must be provided for CIP-42 transactions.',
+    )
+  }
+}

package/src/clients/createClient.ts

@@ -1,39 +1,75 @@
-import type { Chain } from '../types/index.js'
-import type { Requests } from '../types/eip1193.js'
-import { uid } from '../utils/uid.js'
+import type { Address } from 'abitype'
+
+import type { Account, JsonRpcAccount } from '../accounts/types.js'
+import type { Chain } from '../types/chain.js'
 import type {
-  BaseRpcRequests,
-  Transport,
-} from './transports/createTransport.js'
+  EIP1193RequestFn,
+  EIP1474Methods,
+  RpcSchema,
+} from '../types/eip1193.js'
+import type { Prettify } from '../types/utils.js'
+import { parseAccount } from '../utils/accounts.js'
+import { uid } from '../utils/uid.js'
+import type { Transport } from './transports/createTransport.js'
 
 export type ClientConfig<
-  TTransport extends Transport = Transport,
-  TChain extends Chain | undefined = Chain | undefined,
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  accountOrAddress extends Account | Address | undefined =
+    | Account
+    | Address
+    | undefined,
 > = {
+  /** The Account to use for the Client. This will be used for Actions that require an account as an argument. */
+  account?: accountOrAddress | Account | Address | undefined
+  /** Flags for batch settings. */
+  batch?:
+    | {
+        /** Toggle to enable `eth_call` multicall aggregation. */
+        multicall?: boolean | Prettify<MulticallBatchOptions> | undefined
+      }
+    | undefined
   /** Chain for the client. */
-  chain?: TChain
+  chain?: Chain | undefined | chain
   /** A key for the client. */
-  key?: string
+  key?: string | undefined
   /** A name for the client. */
-  name?: string
+  name?: string | undefined
   /**
    * Frequency (in ms) for polling enabled actions & events.
    * @default 4_000
    */
-  pollingInterval?: number
+  pollingInterval?: number | undefined
   /** The RPC transport */
-  transport: TTransport
+  transport: transport
   /** The type of client. */
-  type?: string
+  type?: string | undefined
 }
 
+// TODO: Move `transport` to slot index 2 since `chain` and `account` used more frequently.
+// Otherwise, we end up with a lot of `Client<Transport, chain, account>` in actions.
 export type Client<
-  TTransport extends Transport = Transport,
-  TRequests extends BaseRpcRequests = Requests,
-  TChain extends Chain | undefined = Chain | undefined,
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+  extended extends Extended | undefined = Extended | undefined,
+> = Client_Base<transport, chain, account, rpcSchema> &
+  (extended extends Extended ? extended : unknown) &
+  ExtendFn<transport, chain, account, rpcSchema, extended>
+
+type Client_Base<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
 > = {
+  /** The Account of the Client. */
+  account: account
+  /** Flags for batch settings. */
+  batch?: ClientConfig['batch']
   /** Chain for the client. */
-  chain: TChain
+  chain: chain
   /** A key for the client. */
   key: string
   /** A name for the client. */
@@ -41,39 +77,111 @@ export type Client<
   /** Frequency (in ms) for polling enabled actions & events. Defaults to 4_000 milliseconds. */
   pollingInterval: number
   /** Request function wrapped with friendly error handling */
-  request: TRequests['request']
+  request: EIP1193RequestFn<
+    rpcSchema extends undefined ? EIP1474Methods : rpcSchema
+  >
   /** The RPC transport */
-  transport: ReturnType<TTransport>['config'] & ReturnType<TTransport>['value']
+  transport: ReturnType<transport>['config'] & ReturnType<transport>['value']
   /** The type of client. */
   type: string
   /** A unique ID for the client. */
   uid: string
 }
 
+type ExtendFn<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+  extended extends Extended | undefined = Extended | undefined,
+> = {
+  extend: <const client extends Extended>(
+    fn: (
+      client: Client<transport, chain, account, rpcSchema, extended>,
+    ) => client,
+  ) => Client<
+    transport,
+    chain,
+    account,
+    rpcSchema,
+    Prettify<client> & (extended extends Extended ? extended : unknown)
+  >
+}
+
+type Extended = Prettify<
+  { [key: string]: unknown } & {
+    // disallow redefining base properties
+    [K in keyof Client_Base]?: undefined
+  }
+>
+
+export type MulticallBatchOptions = {
+  /** The maximum size (in bytes) for each calldata chunk. @default 1_024 */
+  batchSize?: number | undefined
+  /** The maximum number of milliseconds to wait before sending a batch. @default 0 */
+  wait?: number | undefined
+}
+
 /**
- * @description Creates a base client with the given transport.
+ * Creates a base client with the given transport.
  */
 export function createClient<
-  TTransport extends Transport,
-  TRequests extends BaseRpcRequests,
-  TChain extends Chain | undefined = undefined,
->({
-  chain,
-  key = 'base',
-  name = 'Base Client',
-  pollingInterval = 4_000,
-  transport,
-  type = 'base',
-}: ClientConfig<TTransport, TChain>): Client<TTransport, TRequests, TChain> {
-  const { config, request, value } = transport({ chain, pollingInterval })
-  return {
-    chain: chain as TChain,
+  transport extends Transport,
+  chain extends Chain | undefined = undefined,
+  accountOrAddress extends Account | Address | undefined = undefined,
+>(
+  parameters: ClientConfig<transport, chain, accountOrAddress>,
+): Prettify<
+  Client<
+    transport,
+    chain,
+    accountOrAddress extends Address
+      ? Prettify<JsonRpcAccount<accountOrAddress>>
+      : accountOrAddress
+  >
+>
+
+export function createClient(parameters: ClientConfig): Client {
+  const {
+    batch,
+    key = 'base',
+    name = 'Base Client',
+    pollingInterval = 4_000,
+    type = 'base',
+  } = parameters
+
+  const chain = parameters.chain
+  const account = parameters.account
+    ? parseAccount(parameters.account)
+    : undefined
+  const { config, request, value } = parameters.transport({
+    chain,
+    pollingInterval,
+  })
+  const transport = { ...config, ...value }
+
+  const client = {
+    account,
+    batch,
+    chain,
     key,
     name,
     pollingInterval,
     request,
-    transport: { ...config, ...value },
+    transport,
     type,
     uid: uid(),
   }
+
+  function extend(base: typeof client) {
+    type ExtendFn = (base: typeof client) => unknown
+    return (extendFn: ExtendFn) => {
+      const extended = extendFn(base) as Extended
+      for (const key in client) delete extended[key]
+      const combined = { ...base, ...extended }
+      return Object.assign(combined, { extend: extend(combined) })
+    }
+  }
+
+  return Object.assign(client, { extend: extend(client) as any })
 }

package/src/clients/createPublicClient.ts

@@ -1,55 +1,68 @@
-import type { PublicRequests } from '../types/eip1193.js'
+import type { Chain } from '../types/chain.js'
+import type { PublicRpcSchema } from '../types/eip1193.js'
+import type { Prettify } from '../types/utils.js'
+import { type Client, type ClientConfig, createClient } from './createClient.js'
+import { type PublicActions, publicActions } from './decorators/public.js'
 import type { Transport } from './transports/createTransport.js'
-import type { Client, ClientConfig } from './createClient.js'
-import { createClient } from './createClient.js'
-import { publicActions } from './decorators/index.js'
-import type { PublicActions } from './decorators/index.js'
-import type { Chain, Prettify } from '../types/index.js'
 
 export type PublicClientConfig<
-  TTransport extends Transport = Transport,
-  TChain extends Chain | undefined = Chain | undefined,
-> = Pick<
-  ClientConfig<TTransport, TChain>,
-  'chain' | 'key' | 'name' | 'pollingInterval' | 'transport'
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+> = Prettify<
+  Pick<
+    ClientConfig<transport, chain>,
+    'batch' | 'chain' | 'key' | 'name' | 'pollingInterval' | 'transport'
+  >
 >
 
 export type PublicClient<
-  TTransport extends Transport = Transport,
-  TChain extends Chain | undefined = Chain | undefined,
-  TIncludeActions extends boolean = true,
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
 > = Prettify<
-  Client<TTransport, PublicRequests, TChain> &
-    (TIncludeActions extends true ? PublicActions<TTransport, TChain> : unknown)
+  Client<
+    transport,
+    chain,
+    undefined,
+    PublicRpcSchema,
+    PublicActions<transport, chain>
+  >
 >
 
 /**
- * @description Creates a public client with a given transport.
+ * Creates a Public Client with a given [Transport](https://viem.sh/docs/clients/intro.html) configured for a [Chain](https://viem.sh/docs/clients/chains.html).
+ *
+ * - Docs: https://viem.sh/docs/clients/public.html
+ *
+ * A Public Client is an interface to "public" [JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/) methods such as retrieving block numbers, transactions, reading from smart contracts, etc through [Public Actions](/docs/actions/public/introduction).
+ *
+ * @param config - {@link PublicClientConfig}
+ * @returns A Public Client. {@link PublicClient}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
  */
 export function createPublicClient<
-  TTransport extends Transport,
-  TChain extends Chain | undefined = undefined,
->({
-  chain,
-  key = 'public',
-  name = 'Public Client',
-  transport,
-  pollingInterval,
-}: PublicClientConfig<TTransport, TChain>): PublicClient<
-  TTransport,
-  TChain,
-  true
-> {
+  transport extends Transport,
+  chain extends Chain | undefined = undefined,
+>(
+  parameters: PublicClientConfig<transport, chain>,
+): PublicClient<transport, chain>
+
+export function createPublicClient(
+  parameters: PublicClientConfig,
+): PublicClient {
+  const { key = 'public', name = 'Public Client' } = parameters
   const client = createClient({
-    chain,
+    ...parameters,
     key,
     name,
-    pollingInterval,
-    transport,
     type: 'publicClient',
-  }) as PublicClient<TTransport, TChain>
-  return {
-    ...client,
-    ...publicActions(client),
-  }
+  })
+  return client.extend(publicActions)
 }

package/src/clients/createTestClient.ts

@@ -1,68 +1,91 @@
-import type { Chain } from '../types/index.js'
-import type { TestRequests } from '../types/eip1193.js'
-import type { Client, ClientConfig } from './createClient.js'
-import { createClient } from './createClient.js'
-import { testActions } from './decorators/index.js'
-import type { TestActions } from './decorators/index.js'
+import type { Account } from '../accounts/types.js'
+import type { ParseAccount } from '../types/account.js'
+import type { Chain } from '../types/chain.js'
+import type { TestRpcSchema } from '../types/eip1193.js'
+import type { Prettify } from '../types/utils.js'
+import { type Client, type ClientConfig, createClient } from './createClient.js'
+import { type TestActions, testActions } from './decorators/test.js'
 import type { Transport } from './transports/createTransport.js'
+import type { Address } from 'abitype'
 
-export type TestClientMode = 'anvil' | 'hardhat'
+export type TestClientMode = 'anvil' | 'hardhat' | 'ganache'
 
 export type TestClientConfig<
-  TMode extends TestClientMode = TestClientMode,
-  TTransport extends Transport = Transport,
-  TChain extends Chain | undefined = Chain | undefined,
-> = Pick<
-  ClientConfig<TTransport, TChain>,
-  'chain' | 'key' | 'name' | 'pollingInterval' | 'transport'
-> & {
-  /** Mode of the test client. Available: "anvil" | "hardhat" */
-  mode: TMode
-}
+  mode extends TestClientMode = TestClientMode,
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  accountOrAddress extends Account | Address | undefined =
+    | Account
+    | Address
+    | undefined,
+> = Prettify<
+  Pick<
+    ClientConfig<transport, chain, accountOrAddress>,
+    'account' | 'chain' | 'key' | 'name' | 'pollingInterval' | 'transport'
+  > & {
+    /** Mode of the test client. */
+    mode: mode | ('anvil' | 'hardhat' | 'ganache') // TODO: Type utility that expands `TestClientMode`
+  }
+>
 
 export type TestClient<
   TMode extends TestClientMode = TestClientMode,
-  TTransport extends Transport = Transport,
-  TChain extends Chain | undefined = Chain | undefined,
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  TAccount extends Account | undefined = Account | undefined,
   TIncludeActions extends boolean = true,
-> = Client<TTransport, TestRequests<TMode>, TChain> &
-  (TIncludeActions extends true ? TestActions : unknown) & {
-    mode: TMode
-  }
+> = Prettify<
+  { mode: TMode } & Client<
+    transport,
+    chain,
+    TAccount,
+    TestRpcSchema<TMode>,
+    TIncludeActions extends true ? TestActions : Record<string, unknown>
+  >
+>
 
 /**
  * @description Creates a test client with a given transport.
  */
+/**
+ * Creates a Test Client with a given [Transport](https://viem.sh/docs/clients/intro.html) configured for a [Chain](https://viem.sh/docs/clients/chains.html).
+ *
+ * - Docs: https://viem.sh/docs/clients/test.html
+ *
+ * A Test Client is an interface to "test" JSON-RPC API methods accessible through a local Ethereum test node such as [Anvil](https://book.getfoundry.sh/anvil/) or [Hardhat](https://hardhat.org/) such as mining blocks, impersonating accounts, setting fees, etc through [Test Actions](https://viem.sh/docs/actions/test/introduction.html).
+ *
+ * @param config - {@link TestClientConfig}
+ * @returns A Test Client. {@link TestClient}
+ *
+ * @example
+ * import { createTestClient, custom } from 'viem'
+ * import { foundry } from 'viem/chains'
+ *
+ * const client = createTestClient({
+ *   mode: 'anvil',
+ *   chain: foundry,
+ *   transport: http(),
+ * })
+ */
 export function createTestClient<
-  TMode extends TestClientMode,
-  TTransport extends Transport,
-  TChain extends Chain | undefined = undefined,
->({
-  chain,
-  key = 'test',
-  name = 'Test Client',
-  mode,
-  pollingInterval,
-  transport,
-}: TestClientConfig<TMode, TTransport, TChain>): TestClient<
-  TMode,
-  TTransport,
-  TChain,
-  true
-> {
-  const client = {
-    ...createClient({
-      chain,
-      key,
-      name,
-      pollingInterval,
-      transport,
-      type: 'testClient',
-    }),
+  mode extends 'anvil' | 'hardhat' | 'ganache', // TODO: Type utility that expands `TestClientMode`
+  transport extends Transport,
+  chain extends Chain | undefined = undefined,
+  accountOrAddress extends Account | Address | undefined = undefined,
+>(
+  parameters: TestClientConfig<mode, transport, chain, accountOrAddress>,
+): TestClient<mode, transport, chain, ParseAccount<accountOrAddress>>
+
+export function createTestClient(parameters: TestClientConfig): TestClient {
+  const { key = 'test', name = 'Test Client', mode } = parameters
+  const client = createClient({
+    ...parameters,
+    key,
+    name,
+    type: 'testClient',
+  })
+  return client.extend((config) => ({
     mode,
-  } as TestClient<TMode, TTransport, TChain>
-  return {
-    ...client,
-    ...testActions(client),
-  }
+    ...testActions({ mode })(config),
+  }))
 }