> ## 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 in development (v0.1.0). APIs may change before stable release.
</Warning>

## 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                       |
| Swap passkey for Argent/Braavos wallet signer                                     | **Core** (`ExternalSigner`)             | Hooks are hardwired to passkey flow              |
| Gasless transactions with any wallet (Argent X, Braavos, Cartridge, DirectSigner) | **Core** (`TxBuilder.sendSponsored()`)  | Uses Chipi's paymaster for gas sponsorship       |

## Installation

<CodeGroup>
  ```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
  ```
</CodeGroup>

## 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

<CardGroup cols={2}>
  <Card title="Amount" icon="calculator" href="/sdk/core/amount">
    Immutable token amount class with BigInt arithmetic, parsing, and formatting.
  </Card>

  <Card title="TxBuilder" icon="layer-group" href="/sdk/core/tx-builder">
    Fluent builder for batching StarkNet multicalls into atomic transactions.
  </Card>

  <Card title="Erc20" icon="coins" href="/sdk/core/erc20">
    Typed ERC20 contract wrapper that returns Amount objects.
  </Card>

  <Card title="TokenRegistry" icon="database" href="/sdk/core/token-registry">
    Token metadata lookup by symbol or address, with network presets.
  </Card>

  <Card title="SignerAdapter" icon="key" href="/sdk/core/signer-adapter">
    Unified signing interface for passkeys, direct keys, and external providers.
  </Card>
</CardGroup>