npm package: @gasfree-kit/core
Description: Shared types, interfaces, and chain configs for gasfree-kit
Latest version: 0.2.0

# @gasfree-kit/core

Shared types, chain metadata, validation helpers, error classes, and seed phrase utilities used across the gasfree-kit SDK.

`@gasfree-kit/core` is the foundation package. It does not send transactions by itself. Instead, it gives the rest of the SDK a common language for chains, balances, addresses, and errors.

## What This Package Is For

Use this package when you want to:

- share SDK-wide types in your app
- read built-in chain metadata
- validate EVM or TON addresses before making requests
- handle gasfree-kit errors in a consistent way
- generate a seed phrase through WDK

## Package Diagram

```
                 ┌──────────────┐
                 │   Your app   │
                 └──────┬───────┘
                        │
         ┌──────────────┼──────────────┐
         v              v              v
  ┌────────────┐ ┌─────────────┐ ┌──────────┐
  │  evm-4337  │ │ ton-gasless │ │ testing  │
  └──────┬─────┘ └──────┬──────┘ └────┬─────┘
         │              │              │
         └──────────────┼──────────────┘
                        v
                 ┌──────────────┐
                 │     core     │
                 └──────────────┘
```

## Installation

```bash
npm install @gasfree-kit/core
```

Peer dependency:

```bash
npm install @tetherto/wdk
```

If you only use `@gasfree-kit/evm-4337` or `@gasfree-kit/ton-gasless`, this package is usually pulled in for you automatically.

## What You Get

| Category     | Main exports                                                                                                    | Why it matters                                                            |
| ------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Types        | `SupportedChain`, `EvmChain`, `SupportedToken`, `TransactionResult`, `GaslessTransferParams`, `GaslessClient`   | Keeps app code and package integrations consistent                        |
| Chain config | `EVM_CHAINS`, `TON_CHAIN`                                                                                       | Gives you built-in chain IDs, RPC URLs, explorer URLs, and USDT addresses |
| Validation   | `validateEvmAddress`, `validateTonAddress`                                                                      | Fails early on malformed recipient or token addresses                     |
| Errors       | `GasfreeError`, `TransactionFailedError`, `InsufficientBalanceError`, `UnsupportedChainError`, `PaymasterError` | Makes error handling predictable across packages                          |
| Seed phrase  | `generateSeedPhrase`                                                                                            | Lets you create a new mnemonic through WDK                                |

## Quick Examples

### Read chain metadata

```ts
import { EVM_CHAINS, TON_CHAIN } from '@gasfree-kit/core';

const base = EVM_CHAINS.base;
console.log(base.chainId); // 8453
console.log(base.usdtAddress);

console.log(TON_CHAIN.endpoint);
console.log(TON_CHAIN.usdtAddress);
```

### Generate a seed phrase

```ts
import { generateSeedPhrase } from '@gasfree-kit/core';

const seedPhrase = await generateSeedPhrase();
```

### Validate addresses before submitting work

```ts
import { validateEvmAddress, validateTonAddress } from '@gasfree-kit/core';

validateEvmAddress('0x1111111111111111111111111111111111111111', 'base');
validateTonAddress('EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs');
```

### Reuse shared types in your app

```ts
import type { GaslessTransferParams, SupportedChain, TransactionResult } from '@gasfree-kit/core';

type TransferJob = {
  chain: SupportedChain;
  params: GaslessTransferParams;
};

function logResult(result: TransactionResult) {
  console.log(result.chain, result.hash, result.success);
}
```

### Handle SDK errors consistently

```ts
import { GasfreeError, InsufficientBalanceError, TransactionFailedError } from '@gasfree-kit/core';

try {
  // call into another gasfree-kit package
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log('Balance issue:', error.message);
  } else if (error instanceof TransactionFailedError) {
    console.log('Transfer failed:', error.message);
  } else if (error instanceof GasfreeError) {
    console.log('SDK error:', error.code, error.message);
  }
}
```

## Export Overview

```ts
import {
  EVM_CHAINS,
  TON_CHAIN,
  generateSeedPhrase,
  validateEvmAddress,
  validateTonAddress,
  GasfreeError,
  InsufficientBalanceError,
  UnsupportedChainError,
  TransactionFailedError,
  PaymasterError,
} from '@gasfree-kit/core';

import type {
  SupportedChain,
  EvmChain,
  NonEvmChain,
  SupportedToken,
  TransactionResult,
  WalletResult,
  GaslessTransferParams,
  GaslessClient,
} from '@gasfree-kit/core';
```

## When To Reach For Other Packages

- Use `@gasfree-kit/evm-4337` when you want ERC-4337 Safe-based USDT transfers on EVM chains.
- Use `@gasfree-kit/ton-gasless` when you want gasless USDT transfers on TON.
- Use `@gasfree-kit/testing` when you want mocks and test helpers inside this monorepo.

## License

MIT