@gelatocloud/gasless 0.0.0

package/index.ts

@@ -0,0 +1,4 @@
+export * from './account/index.js';
+export * from './bundler/index.js';
+export * from './relayer/index.js';
+export * from './types/index.js';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@gelatocloud/gasless",
+  "version": "0.0.0",
+  "author": "Gelato",
+  "description": "Gelato Gasless SDK: All-in-one solution for gasless transactions",
+  "main": "./_dist/index.js",
+  "types": "./_dist/index.d.ts",
+  "typings": "./_dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./_dist/index.d.ts",
+      "import": "./_dist/index.js",
+      "default": "./_dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "4.1.13"
+  },
+  "peerDependencies": {
+    "typescript": "5.9.3",
+    "viem": "2.39.3"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "viem": "2.39.3",
+    "zod": "4.1.13"
+  },
+  "scripts": {
+    "build": "tsc --project ./tsconfig.build.json"
+  }
+}

package/relayer/constants/index.ts

@@ -0,0 +1,2 @@
+export const GELATO_PROD_API = 'https://api.gelato.cloud';
+export const GELATO_STAGING_API = 'https://api.t.gelato.cloud';

package/relayer/evm/actions/getCapabilities.ts

@@ -0,0 +1,22 @@
+import type { Transport } from 'viem';
+import { z } from 'zod';
+import { evmAddressSchema, evmTokenSchema } from '../../../types/index.js';
+
+const capabilitiesByChainSchema = z.object({
+  feeCollector: evmAddressSchema,
+  tokens: z.array(evmTokenSchema)
+});
+
+const capabilitiesSchema = z.record(z.string().pipe(z.coerce.number()), capabilitiesByChainSchema);
+
+export type CapabilitiesByChain = z.infer<typeof capabilitiesByChainSchema>;
+export type Capabilities = z.infer<typeof capabilitiesSchema>;
+
+export const getCapabilities = async (client: ReturnType<Transport>): Promise<Capabilities> => {
+  const result = await client.request({
+    method: 'relayer_getCapabilities',
+    params: []
+  });
+
+  return capabilitiesSchema.parse(result);
+};

package/relayer/evm/actions/getFeeData.ts

@@ -0,0 +1,36 @@
+import type { Address, Transport } from 'viem';
+import { z } from 'zod';
+import { evmTokenSchema } from '../../../types/index.js';
+
+const feeDataSchema = z.object({
+  chainId: z.coerce.number(),
+  context: z.unknown().optional(),
+  expiry: z.number(),
+  gasPrice: z.coerce.bigint(),
+  rate: z.number(),
+  token: evmTokenSchema
+});
+
+export type FeeData = z.infer<typeof feeDataSchema>;
+
+export type GetFeeDataParameters = {
+  chainId: number;
+  token: Address;
+};
+
+export const getFeeData = async (
+  client: ReturnType<Transport>,
+  parameters: GetFeeDataParameters
+): Promise<FeeData> => {
+  const { chainId, token } = parameters;
+
+  const result = await client.request({
+    method: 'relayer_getFeeData',
+    params: {
+      chainId: chainId.toString(),
+      token
+    }
+  });
+
+  return feeDataSchema.parse(result);
+};

package/relayer/evm/actions/getFeeQuote.ts

@@ -0,0 +1,39 @@
+import type { Address, Transport } from 'viem';
+import { z } from 'zod';
+import { evmTokenSchema } from '../../../types/index.js';
+
+const feeQuote = z.object({
+  chainId: z.coerce.number(),
+  context: z.unknown().optional(),
+  expiry: z.number(),
+  fee: z.coerce.bigint(),
+  token: evmTokenSchema
+});
+
+export type FeeQuote = z.infer<typeof feeQuote>;
+
+export type GetFeeQuoteParameters = {
+  chainId: number;
+  gas: bigint;
+  l1Fee?: bigint;
+  token: Address;
+};
+
+export const getFeeQuote = async (
+  client: ReturnType<Transport>,
+  parameters: GetFeeQuoteParameters
+): Promise<FeeQuote> => {
+  const { chainId, gas, l1Fee, token } = parameters;
+
+  const result = await client.request({
+    method: 'relayer_getFeeQuote',
+    params: {
+      chainId: chainId.toString(),
+      gas: gas.toString(),
+      l1Fee: l1Fee ? l1Fee.toString() : undefined,
+      token
+    }
+  });
+
+  return feeQuote.parse(result);
+};

package/relayer/evm/actions/getStatus.ts

@@ -0,0 +1,92 @@
+import type { Transport } from 'viem';
+import { z } from 'zod';
+import { evmAddressSchema, hexData32Schema, hexDataSchema } from '../../../types/index.js';
+
+export enum StatusCode {
+  Pending = 100,
+  Submitted = 110,
+  Included = 200,
+  Rejected = 400,
+  Reverted = 500
+}
+
+const logSchema = z.object({
+  address: evmAddressSchema,
+  data: hexDataSchema,
+  topics: z.array(hexData32Schema)
+});
+
+const receiptSchema = z.object({
+  blockHash: hexData32Schema,
+  blockNumber: z.coerce.bigint(),
+  gasUsed: z.coerce.bigint(),
+  logs: z.array(logSchema).optional(),
+  transactionHash: hexData32Schema
+});
+
+const baseStatusSchema = z.object({
+  chainId: z.coerce.number(),
+  createdAt: z.number()
+});
+
+const pendingStatusSchema = baseStatusSchema.extend({
+  status: z.literal(StatusCode.Pending)
+});
+
+const submittedStatusSchema = baseStatusSchema.extend({
+  hash: hexData32Schema,
+  status: z.literal(StatusCode.Submitted)
+});
+
+const includedStatusSchema = baseStatusSchema.extend({
+  receipt: receiptSchema,
+  status: z.literal(StatusCode.Included)
+});
+
+const rejectedStatusSchema = baseStatusSchema.extend({
+  data: z.unknown().optional(),
+  message: z.string(),
+  status: z.literal(StatusCode.Rejected)
+});
+
+const revertedStatusSchema = baseStatusSchema.extend({
+  data: z.string(),
+  message: z.string().optional(),
+  status: z.literal(StatusCode.Reverted)
+});
+
+export const terminalStatusSchema = z.discriminatedUnion('status', [
+  includedStatusSchema,
+  rejectedStatusSchema,
+  revertedStatusSchema
+]);
+
+export const statusSchema = z.discriminatedUnion('status', [
+  pendingStatusSchema,
+  submittedStatusSchema,
+  includedStatusSchema,
+  rejectedStatusSchema,
+  revertedStatusSchema
+]);
+
+export type TerminalStatus = z.infer<typeof terminalStatusSchema>;
+
+export type Status = z.infer<typeof statusSchema>;
+
+export type GetStatusParameters = {
+  id: string;
+};
+
+export const getStatus = async (
+  client: ReturnType<Transport>,
+  parameters: GetStatusParameters
+): Promise<Status> => {
+  const { id } = parameters;
+
+  const result = await client.request({
+    method: 'relayer_getStatus',
+    params: { id }
+  });
+
+  return statusSchema.parse(result);
+};

package/relayer/evm/actions/index.ts

@@ -0,0 +1,7 @@
+export * from './getCapabilities.js';
+export * from './getFeeData.js';
+export * from './getFeeQuote.js';
+export * from './getStatus.js';
+export * from './sendTransaction.js';
+export * from './sendTransactionSync.js';
+export * from './waitForStatus.js';

package/relayer/evm/actions/sendTransaction.ts

@@ -0,0 +1,33 @@
+import type { Address, Hex, SignedAuthorizationList, Transport } from 'viem';
+import { hexData32Schema, type Payment } from '../../../types/index.js';
+import { formatAuthorization } from '../../../utils/index.js';
+
+export type SendTransactionParameters = {
+  authorizationList?: SignedAuthorizationList;
+  chainId: number;
+  context?: unknown;
+  data: Hex;
+  payment: Payment;
+  to: Address;
+};
+
+export const sendTransaction = async (
+  client: ReturnType<Transport>,
+  parameters: SendTransactionParameters
+): Promise<Hex> => {
+  const { chainId, data, to, payment, context, authorizationList } = parameters;
+
+  const result = await client.request({
+    method: 'relayer_sendTransaction',
+    params: {
+      authorizationList: authorizationList ? authorizationList.map(formatAuthorization) : undefined,
+      chainId: chainId.toString(),
+      context,
+      data,
+      payment,
+      to
+    }
+  });
+
+  return hexData32Schema.parse(result);
+};

package/relayer/evm/actions/sendTransactionSync.ts

@@ -0,0 +1,30 @@
+import type { Transport } from 'viem';
+import { formatAuthorization } from '../../../utils/index.js';
+import { type TerminalStatus, terminalStatusSchema } from './getStatus.js';
+import type { SendTransactionParameters } from './sendTransaction.js';
+
+export type SendTransactionSyncParameters = SendTransactionParameters & {
+  timeout?: number;
+};
+
+export const sendTransactionSync = async (
+  client: ReturnType<Transport>,
+  parameters: SendTransactionSyncParameters
+): Promise<TerminalStatus> => {
+  const { chainId, data, to, payment, context, authorizationList, timeout } = parameters;
+
+  const result = await client.request({
+    method: 'relayer_sendTransactionSync',
+    params: {
+      authorizationList: authorizationList ? authorizationList.map(formatAuthorization) : undefined,
+      chainId: chainId.toString(),
+      context,
+      data,
+      payment,
+      timeout,
+      to
+    }
+  });
+
+  return terminalStatusSchema.parse(result);
+};

package/relayer/evm/actions/waitForStatus.ts

@@ -0,0 +1,24 @@
+import type { Transport } from 'viem';
+import {
+  type GetStatusParameters,
+  getStatus,
+  StatusCode,
+  type TerminalStatus
+} from './getStatus.js';
+
+// TODO: use websockets
+// TODO: make polling interval configurable
+export const waitForStatus = async (
+  client: ReturnType<Transport>,
+  parameters: GetStatusParameters
+): Promise<TerminalStatus> => {
+  while (true) {
+    const status = await getStatus(client, parameters);
+
+    if (status.status !== StatusCode.Pending && status.status !== StatusCode.Submitted) {
+      return status;
+    }
+
+    await new Promise((r) => setTimeout(r, 100));
+  }
+};

package/relayer/evm/index.ts

@@ -0,0 +1,68 @@
+import { type Hex, type HttpTransportConfig, http } from 'viem';
+import { GELATO_PROD_API, GELATO_STAGING_API } from '../constants/index.js';
+import {
+  type Capabilities,
+  type FeeData,
+  type FeeQuote,
+  type GetFeeDataParameters,
+  type GetFeeQuoteParameters,
+  type GetStatusParameters,
+  getCapabilities,
+  getFeeData,
+  getFeeQuote,
+  getStatus,
+  type SendTransactionParameters,
+  type SendTransactionSyncParameters,
+  type Status,
+  sendTransaction,
+  sendTransactionSync,
+  type TerminalStatus,
+  waitForStatus
+} from './actions/index.js';
+
+export * from './actions/index.js';
+
+export type GelatoEvmRelayerClient = {
+  getCapabilities: () => Promise<Capabilities>;
+  getFeeData: (parameters: GetFeeDataParameters) => Promise<FeeData>;
+  getFeeQuote: (parameters: GetFeeQuoteParameters) => Promise<FeeQuote>;
+  getStatus: (parameters: GetStatusParameters) => Promise<Status>;
+  waitForStatus: (parameters: GetStatusParameters) => Promise<TerminalStatus>;
+  sendTransaction: (parameters: SendTransactionParameters) => Promise<Hex>;
+  sendTransactionSync: (parameters: SendTransactionSyncParameters) => Promise<TerminalStatus>;
+};
+
+export type GelatoEvmRelayerClientConfig = {
+  apiKey: string;
+  testnet: boolean;
+};
+
+// TODO: the testnet/mainnet separation won't be necessary in the future
+export const createGelatoEvmRelayerClient = (
+  parameters: GelatoEvmRelayerClientConfig
+): GelatoEvmRelayerClient => {
+  const { apiKey, testnet } = parameters;
+
+  const config: HttpTransportConfig = {
+    fetchOptions: {
+      headers: {
+        'X-API-Key': apiKey
+      }
+    }
+  };
+
+  // TODO: can just use prod endpoint in the future
+  const base = testnet ? GELATO_STAGING_API : GELATO_PROD_API;
+
+  const client = http(`${base}/rpc`, config)({});
+
+  return {
+    getCapabilities: () => getCapabilities(client),
+    getFeeData: (parameters) => getFeeData(client, parameters),
+    getFeeQuote: (parameters) => getFeeQuote(client, parameters),
+    getStatus: (parameters) => getStatus(client, parameters),
+    sendTransaction: (parameters) => sendTransaction(client, parameters),
+    sendTransactionSync: (parameters) => sendTransactionSync(client, parameters),
+    waitForStatus: (parameters) => waitForStatus(client, parameters)
+  };
+};

package/relayer/index.ts

@@ -0,0 +1 @@
+export * from './evm/index.js';

package/tsconfig.build.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true,
+    "noEmit": false,
+    "outDir": "./_dist"
+  },
+  "exclude": [
+    "node_modules",
+    "_dist",
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/*.test.tsx",
+    "**/*.spec.tsx"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "./"
+  }
+}

package/types/error.ts

@@ -0,0 +1,38 @@
+// Note: copied from viem since it doesn't export these
+
+import { BaseError } from 'viem';
+
+export class InvalidBytesLengthError extends BaseError {
+  constructor({
+    size,
+    targetSize,
+    type
+  }: {
+    size: number;
+    targetSize: number;
+    type: 'hex' | 'bytes';
+  }) {
+    super(
+      `${type.charAt(0).toUpperCase()}${type
+        .slice(1)
+        .toLowerCase()} is expected to be ${targetSize} ${type} long, but is ${size} ${type} long.`,
+      { name: 'InvalidBytesLengthError' }
+    );
+  }
+}
+
+export class AccountNotFoundError extends BaseError {
+  constructor({ docsPath }: { docsPath?: string | undefined } = {}) {
+    super(
+      [
+        'Could not find an Account to execute with this Action.',
+        'Please provide an Account with the `account` argument on the Action, or by supplying an `account` to the Client.'
+      ].join('\n'),
+      {
+        docsPath,
+        docsSlug: 'account',
+        name: 'AccountNotFoundError'
+      }
+    );
+  }
+}

package/types/index.ts

@@ -0,0 +1,3 @@
+export * from './error.js';
+export * from './payment.js';
+export * from './schema.js';

package/types/payment.ts

@@ -0,0 +1,23 @@
+import { type Address, zeroAddress } from 'viem';
+
+export enum PaymentType {
+  Token = 'token',
+  Sponsored = 'sponsored'
+}
+
+export type TokenPayment = {
+  type: PaymentType.Token;
+  address: Address;
+};
+
+export type SponsoredPayment = {
+  type: PaymentType.Sponsored;
+};
+
+export type Payment = TokenPayment | SponsoredPayment;
+
+export const sponsored = (): Payment => ({ type: PaymentType.Sponsored });
+
+export const token = (address: Address): Payment => ({ address, type: PaymentType.Token });
+
+export const native = (): Payment => ({ address: zeroAddress, type: PaymentType.Token });

package/types/schema.ts

@@ -0,0 +1,28 @@
+import { getAddress, type Hex } from 'viem';
+import { z } from 'zod';
+
+const hexData32Pattern = /^0x([0-9a-fA-F][0-9a-fA-F]){32}$/;
+const hexDataPattern = /^0x([0-9a-fA-F][0-9a-fA-F])*$/;
+const evmAddressPattern = /^0x([0-9a-fA-F][0-9a-fA-F]){20}$/;
+
+export const hexDataSchema = z
+  .string()
+  .regex(hexDataPattern, { message: 'not valid hex data' })
+  .transform((val) => val as Hex);
+
+export const hexData32Schema = z
+  .string()
+  .regex(hexData32Pattern, { message: 'not valid 32-byte hex data' })
+  .transform((val) => val as Hex);
+
+export const evmAddressSchema = z
+  .string()
+  .regex(evmAddressPattern, { message: 'not a valid EVM address' })
+  .transform((val) => getAddress(val));
+
+export const evmTokenSchema = z.object({
+  address: evmAddressSchema,
+  decimals: z.number()
+});
+
+export type EvmToken = z.infer<typeof evmTokenSchema>;

package/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './payment.js';
+export * from './serialize.js';

package/utils/payment.ts

@@ -0,0 +1,20 @@
+import { type Address, type Call, encodeFunctionData, erc20Abi, zeroAddress } from 'viem';
+
+export const appendPayment = (
+  calls: Call[],
+  token: Address,
+  feeCollector: Address,
+  amount: bigint
+): Call[] => {
+  if (token === zeroAddress) {
+    return [...calls, { to: feeCollector, value: amount }];
+  }
+
+  const data = encodeFunctionData({
+    abi: erc20Abi,
+    args: [feeCollector, amount],
+    functionName: 'transfer'
+  });
+
+  return [...calls, { data, to: token }];
+};

package/utils/serialize.ts

@@ -0,0 +1,91 @@
+// Note: copied from viem since it doesn't export these
+
+import {
+  AccountStateConflictError,
+  InvalidAddressError,
+  isAddress,
+  numberToHex,
+  pad,
+  type RpcAccountStateOverride,
+  type RpcStateMapping,
+  type RpcStateOverride,
+  type SignedAuthorization,
+  StateAssignmentConflictError,
+  type StateMapping,
+  type StateOverride
+} from 'viem';
+import { InvalidBytesLengthError } from '../types/index.js';
+
+type SerializeStateMappingParameters = StateMapping | undefined;
+
+export function serializeStateMapping(
+  stateMapping: SerializeStateMappingParameters
+): RpcStateMapping | undefined {
+  if (!stateMapping || stateMapping.length === 0) return undefined;
+  return stateMapping.reduce((acc, { slot, value }) => {
+    if (slot.length !== 66)
+      throw new InvalidBytesLengthError({
+        size: slot.length,
+        targetSize: 66,
+        type: 'hex'
+      });
+    if (value.length !== 66)
+      throw new InvalidBytesLengthError({
+        size: value.length,
+        targetSize: 66,
+        type: 'hex'
+      });
+    acc[slot] = value;
+    return acc;
+  }, {} as RpcStateMapping);
+}
+
+type SerializeAccountStateOverrideParameters = Omit<StateOverride[number], 'address'>;
+
+export function serializeAccountStateOverride(
+  parameters: SerializeAccountStateOverrideParameters
+): RpcAccountStateOverride {
+  const { balance, nonce, state, stateDiff, code } = parameters;
+  const rpcAccountStateOverride: RpcAccountStateOverride = {};
+  if (code !== undefined) rpcAccountStateOverride.code = code;
+  if (balance !== undefined) rpcAccountStateOverride.balance = numberToHex(balance);
+  if (nonce !== undefined) rpcAccountStateOverride.nonce = numberToHex(nonce);
+  if (state !== undefined) rpcAccountStateOverride.state = serializeStateMapping(state);
+  if (stateDiff !== undefined) {
+    if (rpcAccountStateOverride.state) throw new StateAssignmentConflictError();
+    rpcAccountStateOverride.stateDiff = serializeStateMapping(stateDiff);
+  }
+  return rpcAccountStateOverride;
+}
+
+type SerializeStateOverrideParameters = StateOverride | undefined;
+
+export function serializeStateOverride(
+  parameters?: SerializeStateOverrideParameters
+): RpcStateOverride | undefined {
+  if (!parameters) return undefined;
+  const rpcStateOverride: RpcStateOverride = {};
+  for (const { address, ...accountState } of parameters) {
+    if (!isAddress(address, { strict: false })) throw new InvalidAddressError({ address });
+    if (rpcStateOverride[address]) throw new AccountStateConflictError({ address: address });
+    rpcStateOverride[address] = serializeAccountStateOverride(accountState);
+  }
+  return rpcStateOverride;
+}
+
+export function formatAuthorization(authorization: SignedAuthorization) {
+  return {
+    address: authorization.address,
+    chainId: numberToHex(authorization.chainId),
+    nonce: numberToHex(authorization.nonce),
+    r: authorization.r
+      ? numberToHex(BigInt(authorization.r), { size: 32 })
+      : pad('0x', { size: 32 }),
+    s: authorization.s
+      ? numberToHex(BigInt(authorization.s), { size: 32 })
+      : pad('0x', { size: 32 }),
+    yParity: authorization.yParity
+      ? numberToHex(authorization.yParity, { size: 1 })
+      : pad('0x', { size: 32 })
+  };
+}