> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core SDK

> Transaction primitives for the Chipi SDK ecosystem: Amount, TxBuilder, ERC20, TokenRegistry, and SignerAdapter.

> [!WARNING]
>
> `@chipi-stack/core` is pre-1.0 (currently 0.6.2). APIs may change before the
> stable release.

## What is @chipi-stack/core?

`@chipi-stack/core` provides opt-in transaction primitives for developers who need fine-grained control over StarkNet operations. It complements the existing hooks-based SDKs (Next.js, React, Expo) with lower-level building blocks.

### When to use core vs hooks

| Use Case | Recommended | Why |
| - | - | - |
| Standard transfers in a React app | Hooks (`useTransfer`) | Simpler, handles state management |
| Batch approve + transfer atomically | **Core** (`TxBuilder`) | Hooks don't support multicall batching |
| Display formatted balances | Either | Core's `Amount` class or shared's `formatAmount` |
| Custom contract interactions with fee preview | **Core** (`TxBuilder.estimateFee()`) | Hooks don't expose fee estimation |
| Backend automation with programmatic signing | **Core** (`DirectSigner` + `TxBuilder`) | No React context available |
| Send from the user's own browser wallet (Bramble, Braavos, Ready) | **Core** (`TxBuilder` with starknet.js `WalletAccount`) | The wallet signs and pays gas; hooks are hardwired to the Chipi wallet |
| Sign with a key in your KMS, HSM or signing service | **Core** (`ExternalSigner`) | Any signer that returns `{ r, s }` over a raw hash |
| Gasless transactions (`DirectSigner`, Cartridge, other deployed accounts that sign SNIP-9 typed data) | **Core** (`TxBuilder.sendSponsored()`) | Uses Chipi's paymaster for gas sponsorship. Not verified with Bramble yet; see [TxBuilder](/sdk/core/tx-builder#can-bramble-use-sendsponsored) |

## Installation

```bash npm theme={null}
npm install @chipi-stack/core @chipi-stack/backend
```

```bash yarn theme={null}
yarn add @chipi-stack/core @chipi-stack/backend
```

```bash pnpm theme={null}
pnpm add @chipi-stack/core @chipi-stack/backend
```

### Module formats

`@chipi-stack/core` ships both ESM and CommonJS, so both of these resolve:

```javascript theme={null}
import { TxBuilder } from "@chipi-stack/core"; // ESM
const { TxBuilder } = require("@chipi-stack/core"); // CommonJS
```

> [!WARNING]
>
> Versions before `0.6.0` were ESM-only. Because an `exports` map overrides
> `main`, any CommonJS resolver failed on them with
> `ERR_PACKAGE_PATH_NOT_EXPORTED: No "exports" main defined`. Since
> `@chipi-stack/backend`, `@chipi-stack/chipi-react` and `@chipi-stack/nextjs`
> all depend on core at runtime, the failure surfaced through those packages
> too.
>
> Bundlers (Next.js, Vite, webpack) resolve the `import` condition and were
> never affected, so this only appeared outside the bundler: standalone server
> scripts, cron jobs, `tsx`, `ts-node` and Jest. Note the trigger is CommonJS
> *resolution*, not CommonJS *syntax*, so `import` statements in a `.ts` file
> still failed under `tsx` unless the nearest `package.json` set
> `"type": "module"`.
>
> If you cannot upgrade yet, adding `"type": "module"` to the package.json of
> the script that imports the SDK forces the ESM path and works around it.

## Quick Example

```typescript theme={null}
import { Amount, TxBuilder, Erc20, TokenRegistry, createAccount, DirectSigner } from "@chipi-stack/core";
import { ChipiServerSDK } from "@chipi-stack/backend";

// Create signer + account
const signer = new DirectSigner(process.env.PRIVATE_KEY!, myAddress);
const account = await createAccount({
  signer,
  provider: { nodeUrl: "https://starknet-mainnet.infura.io/v3/..." },
});

// Look up USDC from the built-in token registry
const registry = new TokenRegistry("mainnet");
const usdcInfo = registry.bySymbol("USDC")!;

// Parse a human-readable amount safely (no floating point)
const amount = Amount.parse("10.0", usdcInfo);

// Create a typed ERC20 wrapper
const usdc = new Erc20(usdcInfo, account);

// Check balance
const balance = await usdc.balanceOf(myAddress);
console.log(balance.toFormatted()); // "150.5 USDC"

// Gasless: approve + transfer via Chipi's paymaster
const sdk = new ChipiServerSDK({ apiPublicKey: "pk_...", apiSecretKey: "sk_..." });
const paymaster = sdk.createPaymasterAdapter();

const txHash = await new TxBuilder(account, { paymaster })
  .add(usdc.approveCall(spender, amount))
  .add(usdc.transferCall(recipient, amount))
  .sendSponsored(); // gasless!

// Or direct (user pays gas):
const result = await new TxBuilder(account)
  .add(usdc.approveCall(spender, amount))
  .add(usdc.transferCall(recipient, amount))
  .send();
```

## Package Architecture

```mermaid theme={null}
graph LR
    TYPES["@chipi-stack/types"] --> CORE["@chipi-stack/core"]
    CORE --> AMOUNT["Amount"]
    CORE --> TXBUILDER["TxBuilder"]
    CORE --> ERC20["Erc20"]
    CORE --> REGISTRY["TokenRegistry"]
    CORE --> SIGNER["SignerAdapter"]
```

`core` depends only on `@chipi-stack/types`. It does not modify or depend on `@chipi-stack/shared`, keeping the two packages independent.

## What's Inside

> **[Amount](/sdk/core/amount)**
>
> Immutable token amount class with BigInt arithmetic, parsing, and formatting.

> **[TxBuilder](/sdk/core/tx-builder)**
>
> Fluent builder for batching StarkNet multicalls into atomic transactions.

> **[Erc20](/sdk/core/erc20)**
>
> Typed ERC20 contract wrapper that returns Amount objects.

> **[TokenRegistry](/sdk/core/token-registry)**
>
> Token metadata lookup by symbol or address, with network presets.

> **[SignerAdapter](/sdk/core/signer-adapter)**
>
> Unified signing interface for passkeys, direct keys, and external providers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.