# Abstract — Full Documentation

> Abstract is an Ethereum Layer 2 blockchain built for consumer crypto. It provides native account abstraction, a global smart contract wallet (AGW), and an app discovery portal designed to make onchain experiences as simple as web2 for end users and as powerful as possible for builders.

---

## AI Agent Resources

### SKILL.md

Abstract provides a machine-readable skill file at [docs.abs.xyz/skill.md](https://docs.abs.xyz/skill.md) following the [agentskills.io specification](https://agentskills.io/specification). It describes what AI agents can accomplish with Abstract — deploying smart contracts, integrating wallets, and leveraging account abstraction.

**Key workflows defined in the skill file:**

1. **Smart Contract Deployment:** Initialize project with Abstract config, write Solidity contracts, compile via zksolc, fund deployer, deploy, verify on Abscan.
2. **Wallet Integration:** Install AGW dependencies, wrap app in `AbstractWalletProvider`, implement `useLoginWithAbstract()`, use `useWriteContractSponsored()`, test on testnet.
3. **Session Keys:** Define function scope, create session with duration, store config securely, use `SessionClient` for gasless execution, revoke if needed.

**Critical warnings from the skill file:**
- Abstract uses zksolc compiler, not standard solc — compilation fails with standard tools
- Session keys on mainnet require security review
- Never commit private keys; use `hardhat vars set`
- Verify correct chain IDs to prevent deployment errors

Agents can integrate it using: `npx skills add https://docs.abs.xyz`

### AGW MCP Server

The [Abstract Global Wallet MCP Server](https://mcp.abs.xyz/) enables AI agents to access wallet and blockchain data through the Model Context Protocol. Connect your wallet once, then query wallet, chain, and Portal data from any compatible AI client (Claude Code, Claude Desktop, Cursor, Windsurf).

**Setup:**
```bash
npx -y @abstract-foundation/agw-mcp init --chain-id 2741
```

**Capabilities:**
- **Wallet Data** — Query wallet addresses and token balances
- **Chain Data** — Access blockchain information (gas prices, block data)
- **Portal Data** — Retrieve portfolio summaries from Abstract Portal API

**Package:** `@abstract-foundation/agw-mcp`
**Authentication:** Wallet-based (browser approval required)

---

## Core Concepts

### What is Abstract

Abstract is a Layer 2 network operating atop Ethereum, engineered to deliver consumer-facing blockchain applications at scale with low fees and fast transaction speeds.

**Built on:** ZK Stack foundation

**Type:** Zero-knowledge (ZK) rollup that achieves scalability by executing transactions off-chain, batching them, and verifying batches on Ethereum using ZK proofs.

**Compatibility:** EVM-compatible — existing Ethereum smart contracts function with minimal or no modifications. The network maintains Ethereum's look and feel while offering reduced gas costs and increased transaction throughput.

**Key characteristics:**
- Lower gas fees compared to Ethereum
- Higher transaction throughput
- Backward compatible with Ethereum applications
- Direct portability for dApps with few or no code changes

### Layer 2s

Abstract operates as a layer 2 blockchain that bundles transactions into batches, which are then submitted to Ethereum for security inheritance. It implements a ZK Rollup architecture using the ZK Stack framework.

**Why L2s exist:** Ethereum is constrained to approximately 15 transactions per second with high gas costs. L2s address two primary objectives:

1. **Increase throughput** — Process more transactions per second
2. **Reduce costs** — Lower gas fees for transactions

These improvements must maintain the network's decentralization and security properties.

**ZK Rollup Mechanism:** Zero-Knowledge Rollups employ cryptographic proofs to validate transaction batches posted to Ethereum. Rather than re-executing transactions on-chain, the system uses zero-knowledge proofs (validity proofs) to confirm the correctness of state transitions in the batch without requiring Ethereum to reprocess them.

### Transaction Lifecycle

Abstract processes transactions through four distinct phases, leveraging Ethereum for security via ZK proofs and batch commitments.

**Phase 1 — Abstract (Processed):**
- Transaction executes on Abstract with soft confirmation provided to users
- Sequencer forwards block to prover and creates batches from multiple blocks

**Phase 2 — Ethereum (Sending):**
- Multiple batches committed to Ethereum in a single transaction
- Data submitted as state diffs — showing only blockchain state changes rather than full transaction data
- Batches stored using blobs following EIP-4844 standard

**Phase 3 — Ethereum (Validating):**
- ZK proof generated to validate batches
- Prover creates ZK-SNARK off-chain and submits via `proveBatches` function
- Verifier confirms proof validity on-chain

**Phase 4 — Ethereum (Executing):**
- State finalized after validation completes
- Merkle tree with L2 logs saved by calling `executeBatches`
- State commitments recorded on Ethereum

### Native Account Abstraction

**Account types on Ethereum:**
- **Externally Owned Accounts (EOAs)**: Private key-controlled; can sign and initiate transactions
- **Smart Contract Accounts**: Code-controlled; can only be called, not initiate actions

**What account abstraction enables:**
- Key recovery mechanisms
- Security controls (spending limits, session keys)
- Alternative gas payment options and sponsorship
- Multi-transaction batching
- Flexible signature validation

**Abstract's native approach:** Account abstraction is implemented at the protocol level. All accounts on Abstract are smart contract accounts and all transactions go through the same transaction lifecycle — eliminating parallel systems. EOA wallets (MetaMask, etc.) are converted to `DefaultAccount` contracts during transaction processing.

### Abstract Global Wallet (AGW)

Abstract Global Wallet is a cross-application smart contract wallet that users can create to interact with any application built on Abstract, powered by native account abstraction. AGW enables streamlined user onboarding through familiar authentication methods (email, social accounts, passkeys) with single-signup access across all Abstract applications.

**Quick start:**
```bash
npx @abstract-foundation/create-abstract-app@latest my-app
```

**Key integration packages:**

| Package | Type | Built on | NPM |
|---|---|---|---|
| `agw-react` | React hooks and components for login + transaction approval | Wagmi | `@abstract-foundation/agw-react` |
| `agw-client` | JS utility library for wallet actions and utility functions | Viem | `@abstract-foundation/agw-client` |

---

## Getting Started

### Connect to Abstract

**Mainnet:**

| Property | Value |
|---|---|
| Chain ID | `2741` |
| RPC URL | `https://api.mainnet.abs.xyz` |
| WebSocket | `wss://api.mainnet.abs.xyz/ws` |
| Block Explorer | https://abscan.org/ |
| Verification API | `https://api.abscan.org/api` |
| Currency | ETH |

**Testnet:**

| Property | Value |
|---|---|
| Chain ID | `11124` |
| RPC URL | `https://api.testnet.abs.xyz` |
| WebSocket | `wss://api.testnet.abs.xyz/ws` |
| Block Explorer | https://sepolia.abscan.org/ |
| Verification API | `https://api-sepolia.abscan.org/api` |
| Currency | ETH |

### Start Building

Abstract is EVM compatible; however, there are differences that enable more powerful user experiences.

**Smart contract development (two primary frameworks):**
- **Hardhat**: Set up a Hardhat plugin to compile contracts for Abstract
- **Foundry**: Use a Foundry fork for contract compilation

**Frontend application libraries:**
- **Ethers**: Quick start with Ethers v6
- **Viem**: React + TypeScript setup using Viem
- **Thirdweb**: React + TypeScript integration with thirdweb SDK

### AGW Getting Started

**New projects:**
```bash
npx @abstract-foundation/create-abstract-app@latest my-app
```

**Existing project integrations:** Native Integration, Privy, ConnectKit, Dynamic, RainbowKit, Thirdweb — each provides tailored setup instructions to maintain compatibility with your chosen wallet connection framework.

---

## Abstract Global Wallet - Client Actions

### deployContract

Deploy smart contracts from the Abstract Global Wallet via the AbstractClient.

```tsx
import { useAbstractClient } from "@abstract-foundation/agw-react";

export default function DeployContract() {
    const { data: agwClient } = useAbstractClient();

    async function deployContract() {
        if (!agwClient) return;
        const hash = await agwClient.deployContract({
            abi: erc20Abi,
            account: agwClient.account,
            bytecode: "0x...",
            chain: abstractTestnet,
            args: [],
        });
    }
}
```

**Required Parameters:** `abi` (Abi), `bytecode` (string), `account` (Account), `chain` (Chain)

**Optional Parameters:** `args`, `deploymentType` (`'create'` | `'create2'` | `'createAccount'` | `'create2Account'`), `factoryDeps`, `salt`, `gasPerPubdata`, `paymaster`, `paymasterInput`

**Returns:** `Hex` transaction hash.

### sendTransaction

Signs and submits transactions using the Abstract Global Wallet.

```tsx
const hash = await agwClient.sendTransaction({
    to: "0x273B3527BF5b607dE86F504fED49e1582dD2a1C6",
    data: "0x69",
});
```

**Parameters:** `to` (Address), `from` (Address), `data` (Hex), `gas` (bigint), `value` (bigint), `maxFeePerGas` (bigint), `maxPriorityFeePerGas` (bigint), `paymaster` (Account | Address), `paymasterInput` (Hex)

**Paymaster Example:**
```tsx
const hash = await agwClient.sendTransaction({
    to: "0x273B3527BF5b607dE86F504fED49e1582dD2a1C6",
    data: "0x69",
    paymaster: "0x5407B5040dec3D339A9247f3654E59EEccbb6391",
    paymasterInput: getGeneralPaymasterInput({ innerInput: "0x" }),
});
```

### sendCalls

Submits multiple transactions atomically, implementing EIP-5792.

```tsx
sendCalls({
    calls: [
        {
            to: TOKEN_ADDRESS,
            data: encodeFunctionData({
                abi: erc20Abi,
                functionName: "approve",
                args: [ROUTER_ADDRESS, parseUnits("100", 18)],
            }),
        },
        {
            to: ROUTER_ADDRESS,
            data: encodeFunctionData({
                abi: routerAbi,
                functionName: "swapExactTokensForETH",
                args: [/* ... */],
            }),
        },
    ],
});
```

**Parameters:** `calls` (Array<Call>), `atomicRequired` (boolean), `capabilities.paymaster` ({ address, data? })

### writeContract

Calls smart contract functions through the Abstract Global Wallet.

```tsx
const hash = await agwClient.writeContract({
    abi: parseAbi(["function mint(address,uint256) external"]),
    address: "0xC4822AbB9F05646A9Ce44EFa6dDcda0Bf45595AA",
    functionName: "mint",
    args: ["0x273B3527BF5b607dE86F504fED49e1582dD2a1C6", BigInt(1)],
});
```

**Parameters:** `address` (Address), `abi` (Abi), `functionName` (string), `args` (unknown[]), `value` (bigint), `paymaster`, `paymasterInput`

### signMessage

Signs messages using EIP-1271 standard for contract signature verification.

```tsx
const signature = await agwClient.signMessage({
    message: "Hello, Abstract!",
});
```

**Server-side verification:**
```tsx
const isValid = await publicClient.verifyMessage({
    address: walletAddress,
    message: "Hello, Abstract!",
    signature,
});
```

### signTransaction

Signs transactions using the Abstract Global Wallet. Transactions are signed by the wallet's approved signer account (an EOA).

```tsx
const signature = await agwClient.signTransaction({
    to: "0x273B3527BF5b607dE86F504fED49e1582dD2a1C6",
    data: "0x69",
});
```

### getSmartAccountAddressFromInitialSigner

Deterministically derives the AGW smart account address before deployment.

```tsx
import { getSmartAccountAddressFromInitialSigner } from "@abstract-foundation/agw-client";

const smartAccountAddress = await getSmartAccountAddressFromInitialSigner(
    initialSignerAddress,
    publicClient
);
```

**Parameters:** `initialSigner` (Address), `publicClient` (PublicClient)

### transformEIP1193Provider

Adapts standard EIP-1193 providers to work with Abstract Global Wallet.

```tsx
import { transformEIP1193Provider } from "@abstract-foundation/agw-client";

const agwProvider = transformEIP1193Provider({
    provider: originalProvider,
    chain: abstractTestnet,
});
```

Intercepts `eth_accounts`, `eth_signTransaction`, and `eth_sendTransaction` — all other methods pass through unchanged.

---

## Abstract Global Wallet - Session Keys

### Session Keys Overview

Session keys are temporary credentials that allow applications to execute pre-approved actions on behalf of an Abstract Global Wallet without requiring owner signatures for each transaction.

**Key Characteristics:**
- Scoped actions with specific signer and expiration
- No user confirmation needed per transaction
- Testnet permissionless; mainnet requires security review

**Implementation Steps:**
1. Create session key with `createSession` or `useCreateSession`
2. Store session configuration securely
3. Execute transactions via `SessionClient`
4. Optional: revoke with `revokeSessions()`

### Going to Production

Session keys on mainnet are subject to security restrictions through the Session Key Policy Registry contract (`0xA146c7118A46b32aBD0e1ACA41DF4e61061b6b93`).

**Best Practices:**
- Generate unique signer accounts per session
- Store encrypted in browser local storage
- Policies using `approve` or `setApprovalForAll` require constraints limiting approvals to specific contract addresses

### createSession

Creates a session key with granular controls over function calls, transfers, gas fees, and expiration.

```tsx
const { session } = await agwClient.createSession({
    session: {
        signer: sessionSigner.address,
        expiresAt: BigInt(Math.floor(Date.now() / 1000) + 60 * 60 * 24),
        feeLimit: {
            limitType: LimitType.Lifetime,
            limit: parseEther("1"),
            period: BigInt(0),
        },
        callPolicies: [{
            target: "0xC4822AbB9F05646A9Ce44EFa6dDcda0Bf45595AA",
            selector: toFunctionSelector("mint(address,uint256)"),
            valueLimit: { limitType: LimitType.Unlimited, limit: BigInt(0), period: BigInt(0) },
            maxValuePerUse: BigInt(0),
            constraints: [],
        }],
        transferPolicies: [],
    },
});
```

**Limit Types:** `Unlimited` (0), `Lifetime` (1), `Allowance` (2 — per time period)

### createSessionClient

Creates a `SessionClient` directly without requiring an existing AbstractClient.

```tsx
import { createSessionClient } from "@abstract-foundation/agw-client/sessions";

const sessionClient = createSessionClient({
    account: "0x1234...",
    chain: abstractTestnet,
    signer: sessionSigner,
    session: sessionConfig,
    transport: http(),
});
```

### toSessionClient

Creates a `SessionClient` from an existing `AbstractClient`.

```tsx
const sessionClient = agwClient.toSessionClient(sessionSigner, session);
const hash = await sessionClient.writeContract({ /* ... */ });
```

### getSessionHash

Computes a keccak256 hash of a session key configuration.

```tsx
const sessionHash = getSessionHash(sessionConfig);
```

### getSessionStatus

Returns `SessionStatus` enum: `NotInitialized` (0), `Active` (1), `Closed` (2), `Expired` (3).

```tsx
const status = await agwClient.getSessionStatus(sessionHashOrConfig);
```

### revokeSessions

Invalidates existing session keys.

```tsx
await agwClient.revokeSessions({ session: existingSession });
await agwClient.revokeSessions({ session: [session1, session2] });
await agwClient.revokeSessions({ session: "0x1234..." });
```

---

## Abstract Global Wallet - React

### AbstractWalletProvider

Wrapper component that provides AGW context to your application.

```tsx
import { AbstractWalletProvider } from "@abstract-foundation/agw-react";
import { abstract } from "viem/chains";

const App = () => (
    <AbstractWalletProvider chain={abstract}>
        {/* Your application */}
    </AbstractWalletProvider>
);
```

**Props:** `chain` (Chain, required), `transport` (Transport, optional), `queryClient` (QueryClient, optional)

### useLoginWithAbstract

Hook for user authentication. Returns `login` (opens signup/login modal) and `logout` (disconnects wallet).

```tsx
const { login, logout } = useLoginWithAbstract();
```

### useAbstractClient

Hook for creating and managing an Abstract client instance.

```tsx
const { data: abstractClient, isLoading, error } = useAbstractClient();

const hash = await abstractClient.sendTransaction({
    to: "0x8e729E23CDc8bC21c37a73DA4bA9ebdddA3C8B6d",
    data: "0x69",
});
```

### useWriteContractSponsored

Hook for executing smart contract transactions with gas fees covered by a paymaster.

```tsx
const { writeContractSponsored } = useWriteContractSponsored();

writeContractSponsored({
    abi: contractAbi,
    address: "0xC4822AbB9F05646A9Ce44EFa6dDcda0Bf45595AA",
    functionName: "mint",
    args: ["0x273B...", BigInt(1)],
    paymaster: "0x5407B5040dec3D339A9247f3654E59EEccbb6391",
    paymasterInput: getGeneralPaymasterInput({ innerInput: "0x" }),
});
```

### useCreateSession

Hook for creating session keys.

```tsx
const { createSessionAsync } = useCreateSession();
const { session, transactionHash } = await createSessionAsync({ session: sessionConfig });
```

### useRevokeSessions

Hook for revoking session keys.

```tsx
const { revokeSessionsAsync } = useRevokeSessions();
await revokeSessionsAsync({ sessions: existingSessionConfig });
```

### useGlobalWalletSignerAccount

Retrieves the approved signer account (underlying EOA) for the connected AGW.

```tsx
const { address, status } = useGlobalWalletSignerAccount();
```

### useGlobalWalletSignerClient

Retrieves a wallet client for the approved signer (EOA), enabling direct transaction signing.

```tsx
const { data: client } = useGlobalWalletSignerClient();
```

### Native Integration

**Installation:**
```bash
npm install @abstract-foundation/agw-react @abstract-foundation/agw-client wagmi viem@2.x @tanstack/react-query
```

The provider automatically wraps your app in both `WagmiProvider` and `QueryClientProvider`. For Next.js App Router, create a separate client component with the `"use client"` directive.

---

## AGW Third-Party Integrations

### Privy

Uses `AbstractPrivyProvider` component. Enable Abstract in the Privy dashboard under Ecosystem > Integrations.

```tsx
import { AbstractPrivyProvider } from "@abstract-foundation/agw-react/privy";

<AbstractPrivyProvider appId="your-privy-app-id">
    {children}
</AbstractPrivyProvider>
```

Login: `useAbstractPrivyLogin()` returns `login` and `link` functions.

### ConnectKit

Add `abstractWalletConnector()` to your Wagmi config connectors array.

```tsx
import { abstractWalletConnector } from "@abstract-foundation/agw-react/connectors";

export const config = createConfig({
    connectors: [abstractWalletConnector()],
    chains: [abstractTestnet],
    transports: { [abstractTestnet.id]: http() },
});
```

### Dynamic

Uses `AbstractEvmWalletConnectors` from `@dynamic-labs-connectors/abstract-global-wallet-evm`.

```tsx
import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core";
import { AbstractEvmWalletConnectors } from "@dynamic-labs-connectors/abstract-global-wallet-evm";

<DynamicContextProvider settings={{
    environmentId: "your-dynamic-environment-id",
    walletConnectors: [AbstractEvmWalletConnectors],
}}>
    {children}
</DynamicContextProvider>
```

### RainbowKit

Uses `abstractWallet` connector from `@abstract-foundation/agw-react/connectors`.

```tsx
import { connectorsForWallets } from "@rainbow-me/rainbowkit";
import { abstractWallet } from "@abstract-foundation/agw-react/connectors";

export const connectors = connectorsForWallets(
    [{ groupName: "Abstract", wallets: [abstractWallet] }],
    { appName: "Your App Name", projectId: "YOUR_PROJECT_ID" }
);
```

### Reown

Follow the [Reown quickstart](https://docs.reown.com/appkit/overview#quickstart) guide. Configure `abstract` or `abstractTestnet` as your chain.

### Thirdweb

Uses `abstractWallet()` from `@abstract-foundation/agw-react/thirdweb`.

```tsx
import { abstractWallet } from "@abstract-foundation/agw-react/thirdweb";

<ConnectButton
    client={client}
    wallets={[abstractWallet()]}
    accountAbstraction={{ chain: abstractTestnet, sponsorGas: true }}
/>
```

### Crossmint (Fiat On-Ramp)

Enables checkout flows for purchasing on-chain items using fiat currency (credit cards, Google Pay, Apple Pay).

```tsx
<CrossmintEmbeddedCheckout
    lineItems={{
        collectionLocator: `crossmint:${COLLECTION_ID}`,
        callData: { totalPrice: "0.001", quantity: 1, to: address },
    }}
    recipient={{ walletAddress: address }}
    payment={{ crypto: { enabled: false }, fiat: { enabled: true } }}
/>
```

---

## Smart Contracts - Foundry

### Get Started

Install the zkSync-compatible Foundry fork:

```bash
curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash
foundryup-zksync
```

Create project:
```bash
forge init my-abstract-project && cd my-abstract-project
```

Update `foundry.toml`:
```toml
[profile.default]
src = 'src'
libs = ['lib']
fallback_oz = true

[profile.default.zksync]
enable_eravm_extensions = true
```

Compile: `forge build --zksync`

### Deploying Contracts

Import wallet and deploy:
```bash
cast wallet import myKeystore --interactive

forge create src/Counter.sol:Counter \
    --account myKeystore \
    --rpc-url https://api.testnet.abs.xyz \
    --chain 11124 \
    --zksync \
    --verify \
    --verifier etherscan \
    --verifier-url https://api-sepolia.abscan.org/api \
    --etherscan-api-key TACK2D1RGYX9U7MC31SZWWQ7FCWRYQ96AD \
    --broadcast
```

For mainnet, use `--rpc-url https://api.mainnet.abs.xyz --chain 2741`.

### Testing Contracts

```bash
forge test --zksync
```

Fork testing:
```bash
forge test --zksync --fork-url https://api.testnet.abs.xyz
```

Local node testing:
```bash
anvil-zksync
forge test --zksync --fork-url http://localhost:8011
```

### Verifying Contracts

```bash
forge verify-contract <contract-address> <file-path>:<contract-name> \
    --chain abstract-testnet \
    --etherscan-api-key <api-key> \
    --zksync
```

---

## Smart Contracts - Hardhat

### Get Started

**Prerequisites:** Node.js v18.0.0+

```bash
mkdir my-abstract-project && cd my-abstract-project
npx hardhat init
npm install -D @matterlabs/hardhat-zksync zksync-ethers@6 ethers@6
```

Configure `hardhat.config.ts`:
```typescript
import { HardhatUserConfig } from "hardhat/config";
import "@matterlabs/hardhat-zksync";

const config: HardhatUserConfig = {
    zksolc: { version: "latest" },
    defaultNetwork: "abstractTestnet",
    networks: {
        abstractTestnet: {
            url: "https://api.testnet.abs.xyz",
            ethNetwork: "sepolia",
            zksync: true,
            chainId: 11124,
        },
        abstractMainnet: {
            url: "https://api.mainnet.abs.xyz",
            ethNetwork: "mainnet",
            zksync: true,
            chainId: 2741,
        },
    },
    solidity: { version: "0.8.24" },
};
```

Compile: `npx hardhat clean && npx hardhat compile --network abstractTestnet`

### Deploying Contracts

```typescript
import { Wallet } from "zksync-ethers";
import { Deployer } from "@matterlabs/hardhat-zksync";

export default async function (hre) {
    const wallet = new Wallet(vars.get("DEPLOYER_PRIVATE_KEY"));
    const deployer = new Deployer(hre, wallet);
    const artifact = await deployer.loadArtifact("HelloAbstract");
    const contract = await deployer.deploy(artifact);
}
```

Deploy: `npx hardhat deploy-zksync --script deploy.ts --network abstractTestnet`

**Deployment Types:** `"create"` (default), `"create2"` (deterministic), `"createAccount"`, `"create2Account"`

### Testing and Verifying

Test: `npx hardhat test --network abstractTestnet`

Local node: `npx zksync-cli dev start` then `npx hardhat test --network inMemoryNode`

Verify: `npx hardhat verify --network abstractTestnet <contract-address>`

---

## Application SDKs

### Viem

```bash
npm install viem
```

```javascript
import { createPublicClient, createWalletClient, custom, http } from 'viem'
import { abstractTestnet } from 'viem/chains'
import { eip712WalletActions } from 'viem/zksync'

const walletClient = createWalletClient({
    chain: abstractTestnet,
    transport: custom(window.ethereum!),
}).extend(eip712WalletActions());

const publicClient = createPublicClient({
    chain: abstractTestnet,
    transport: http(),
});
```

Supports paymaster transactions and smart contract wallets via `toSmartAccount`.

### Ethers

```bash
npm install zksync-ethers@6 ethers@6
```

```javascript
import { Provider, Wallet } from "zksync-ethers";

const provider = new Provider("https://api.mainnet.abs.xyz");
const wallet = new Wallet(privateKey, provider);
```

### Thirdweb

```bash
npx thirdweb create app --legacy-peer-deps
```

Use `abstractTestnet` or `abstract` from `thirdweb/chains`.

### ZKsync CLI

```bash
npm install -g zksync-cli
```

Commands: `dev` (local environment), `create` (scaffold projects), `contract` (interact with contracts), `transaction`, `wallet`, `bridge`, `config chains`.

---

## Architecture

### L1 Rollup Contracts

Smart contracts deployed on Ethereum that store state diffs, receive and verify validity proofs, and enable cross-chain communication.

**Key Mainnet L1 Contracts:**

| Contract | Address |
|----------|---------|
| Diamond Proxy | `0x2EDc71E9991A962c7FE172212d1aA9E50480fBb9` |
| BridgeHub Proxy | `0x303a465b659cbb0ab36ee643ea362c509eeb5213` |
| State Transition Proxy | `0xc2ee6b6af7d616f6e27ce7f4a451aedc2b0f5f5c` |
| Verifier | `0x70f3fbf8a427155185ec90bed8a3434203de9604` |
| Shared Bridge | `0xd7f9f54194c633f36ccd5f3da84ad4a1c38cb2cb` |

### Sequencer

The sequencer comprises interconnected services:
- **RPC**: Exposes JSON-RPC API (HTTP and WebSocket)
- **Sequencer**: Processes L2 transactions, organizes into blocks, validates compliance
- **ETH Operator**: Manages L1 integration, monitors events, batches transactions

### Prover and Verifier

**Proof Generation (3 steps):**
1. **Witness Generation** — Cryptographic knowledge demonstrating transaction validity
2. **Circuit Execution** — Verifies correct VM operation using Boojum
3. **Proof Compression** — Converts ZK-STARK to succinct ZK-SNARK for on-chain verification

The ZK-SNARK is submitted to L1 via `proveBatches` and verified by the verifier contract.

### AGW Architecture

**Two-Step Account Generation:**

**Step 1 — EOA Creation** (via Privy Embedded Wallets):
- Private key splits into 3 shards using Shamir's Secret Sharing (2 of 3 required)
- Device Share (local browser), Auth Share (Privy servers), Recovery Share (user's cloud)

**Step 2 — Smart Contract Wallet Deployment:**
- EOA's public key authorizes smart contract wallet deployment
- Fork of Clave contracts with secp256k1 signer and EIP-712 signature validation
- Built-in: account recovery, paymaster sponsorship, multiple signer support, passkey compatibility

---

## EVM Differences

### Overview

Abstract is EVM-compatible but uses the ZKsync VM with different bytecode. These differences optimize for zero-knowledge proofs and enable more powerful developer capabilities.

### Contract Deployment

Abstract stores contract bytecode hashes on-chain while publishing actual bytecode to Ethereum. All deployments use the `ContractDeployer` system contract (`0x0000000000000000000000000000000000008006`) via EIP-712 transactions (type 113). Deployments fail with `the code hash is not known` if bytecode is not published.

### Key Opcode Differences

| Opcode | Behavior |
|--------|----------|
| COINBASE | Returns `0x8001` (Bootloader contract) |
| DIFFICULTY/PREVRANDAO | Constant `2500000000000000` |
| BASEFEE | Dynamic, typically 0.25 gwei |
| SELFDESTRUCT, CALLCODE, PC | Compile-time errors |
| EXTCODECOPY | Compile-time error — bytecode inaccessible |
| CREATE/CREATE2 | Address derivation differs from Ethereum |

### EVM Interpreter

Abstract also provides an EVM bytecode interpreter for deploying unmodified EVM contracts. Code hashes prefixed `0x01` are native ZKsync VM; `0x02` triggers the EVM interpreter. Gas costs are 150-400% higher for interpreted contracts.

### Gas Fees

**Fee Components:**
- **Offchain Fee:** Fixed ~$0.001 per transaction (L2 state storage and proof generation)
- **Onchain Fee:** Variable, influenced by Ethereum gas prices (proof verification and state publishing)

Data is published as state deltas only, not full transaction data.

### Nonces

Abstract employs a dual-nonce system:
- **Transaction nonce**: Validates transactions
- **Deployment nonce**: Increments upon successful contract deployment

Starting deployment nonce is `0` (vs Ethereum's `1`). Failed deployments do not increment nonce.

### Best Practices

**Use `call` over `.send` or `.transfer`:**
```solidity
(bool success, ) = addr.call{value: x}("");
require(success, "Transfer failed.");
```

Since all Abstract accounts are smart contracts, recipients may need more than the 2300 gas stipend that `send`/`transfer` provide.

---

## Native Account Abstraction

### Transaction Flow

**Step 1 — Submission:** Transactions submitted via JSON-RPC. The `from` field can reference a smart contract address.

**Step 2 — Bootloader Processing:** Validates nonce, detects account type, converts EOAs to DefaultAccount.

**Step 3 — Account Validation & Execution:**
1. `validateTransaction()` — Custom validation logic
2. `executeTransaction()` — Executes if validation passes
3. `payForTransaction()` or `prepareForPaymaster()` — Handles gas payment

**Step 4 — Paymaster Processing (Optional):**
1. `validateAndPayForPaymasterTransaction()` — Verifies willingness to pay
2. `postTransaction()` — Optional post-transaction logic

### Smart Contract Wallets

All accounts implement the `IAccount` interface:

```bash
npm install @matterlabs/zksync-contracts
```

```solidity
import {IAccount} from "@matterlabs/zksync-contracts/l2/system-contracts/interfaces/IAccount.sol";

contract SmartAccount is IAccount {
    // Implement: validateTransaction, executeTransaction,
    // executeTransactionFromOutside, payForTransaction, prepareForPaymaster
}
```

Deploy with `"createAccount"` deployment type. Send transactions using EIP-712 (type 113).

### Paymasters

Paymasters sponsor gas fees. Must implement `IPaymaster`:

```solidity
function validateAndPayForPaymasterTransaction(
    bytes32 _txHash, bytes32 _suggestedSignedHash,
    Transaction calldata _transaction
) external payable returns (bytes4 magic, bytes memory context);

function postTransaction(
    bytes calldata _context, Transaction calldata _transaction,
    bytes32 _txHash, bytes32 _suggestedSignedHash,
    ExecutionResult _txResult, uint256 _maxRefundedGas
) external payable;
```

Reference implementations: General Paymaster and Approval-Based Paymaster (ERC-20 gas payments).

### Signature Validation

Smart contract accounts use EIP-1271. `isValidSignature` returns `0x1626ba7e` on success.

```solidity
import { SignatureChecker } from "@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol";
```

---

## System Contracts

### Overview

System contracts are specialized smart contracts with elevated privileges deployed at genesis, providing essential support for EVM opcodes unavailable in the ZK-EVM.

**Key System Contracts:**

| Contract | Address | Purpose |
|----------|---------|---------|
| ContractDeployer | `0x...8006` | Deploys smart contracts |
| NonceHolder | `0x...8003` | Tracks deployment and transaction nonces |
| L1Messenger | `0x...8008` | Sends messages from Abstract to Ethereum |
| L2BaseToken | `0x...800a` | Manages ETH balances |
| AccountCodeStorage | `0x...8002` | Stores code hashes for accounts |
| KnownCodesStorage | `0x...8004` | Registry of known contract code hashes |
| Compressor | `0x...800e` | Compresses bytecodes and state diffs for L1 |
| SystemContext | `0x...800b` | Stores chainId, gasPrice, baseFee, etc. |

### Using System Contracts

```bash
npm install @matterlabs/zksync-contracts
```

```solidity
import "@matterlabs/zksync-contracts/l2/system-contracts/interfaces/IAccount.sol";
import { BOOTLOADER_FORMAL_ADDRESS } from "@matterlabs/zksync-contracts/l2/system-contracts/Constants.sol";
```

The `isSystem` flag is required when calling ContractDeployer or NonceHolder. Use `SystemContractsCaller` library.

**Configuration:** Hardhat: `enableEraVMExtensions: true` | Foundry: `enable_eravm_extensions = true`

---

## Ecosystem Services

### Bridges

| Service | URL |
|---------|-----|
| Stargate | https://stargate.finance/bridge |
| Relay | https://www.relay.link/ |
| Jumper | https://jumper.exchange/ |
| Symbiosis | https://symbiosis.finance/ |
| thirdweb | https://thirdweb.com/bridge?chainId=2741 |
| deBridge | https://app.debridge.com |

### Paymasters

- **Zyfi** — Native Account Abstraction provider. [Docs](https://docs.zyfi.org/integration-guide/paymasters-integration/sponsored-paymaster)

### Oracles

- **Gelato VRF** — Verifiable Random Function. [Docs](https://docs.gelato.network/web3-services/vrf)
- **Pyth Price Feeds** — Real-time price data. [Docs](https://docs.pyth.network/price-feeds)
- **Pyth Entropy** — Randomness generation. [Docs](https://docs.pyth.network/entropy)

### Data & Indexing

Alchemy, Ghost (GhostGraph), Goldsky, The Graph, Reservoir, Mobula, SQD, Zapper

### RPC Providers

| Provider | URL |
|----------|-----|
| Alchemy | https://www.alchemy.com/abstract |
| BlastAPI | https://docs.blastapi.io/blast-documentation/apis-documentation/core-api/abstract |
| QuickNode | https://www.quicknode.com/docs/abstract |
| dRPC | https://drpc.org/chainlist/abstract |

### Automation

- **Gelato Web3 Functions** — [Docs](https://docs.gelato.network/web3-services/web3-functions)
- **OpenZeppelin Defender** — [Info](https://www.openzeppelin.com/defender)

### Interoperability

- **LayerZero** — [Docs](https://docs.layerzero.network/v2)
- **Hyperlane** — [Docs](https://docs.hyperlane.xyz/docs/intro)

### Multi-Sig Wallets

- **Safe** — https://safe.abs.xyz/

### Relayers

- **Gelato Relay** — [Docs](https://docs.gelato.network/web3-services/relay)

### Token Distribution

- **Sablier** — https://sablier.com

---

## Tooling

### Block Explorers

| Network | Explorer |
|---------|----------|
| Mainnet | https://abscan.org/ |
| Testnet | https://sepolia.abscan.org/ |

### Bridges

Native bridge (free, gas excluded): L1→L2 ~15 minutes, L2→L1 up to 24 hours.

- Mainnet: https://portal.mainnet.abs.xyz/bridge/
- Testnet: https://portal.testnet.abs.xyz/bridge/

### Deployed Contracts

**Currencies:**

| Token | Mainnet | Testnet |
|-------|---------|---------|
| WETH9 | `0x3439153EB7AF838Ad19d56E1571FBD09333C2809` | `0x9EDCde0257F2386Ce177C3a7FCdd97787F0D841d` |
| USDC | `0x84A71ccD554Cc1b02749b35d22F684CC8ec987e1` | `0xe4C7fBB0a626ed208021ccabA6Be1566905E2dFc` |
| USDT | `0x0709F39376dEEe2A2dfC94A58EdEb2Eb9DF012bD` | — |

**Uniswap V2:** Factory `0x566d7510dEE58360a64C9827257cF6D0Dc43985E`, Router02 `0xad1eCa41E6F772bE3cb5A48A6141f9bcc1AF9F7c`

**Safe:** Multi-sig at https://safe.abs.xyz/

### Faucets

Abstract Testnet: Alchemy (no signup), Triangle (no signup), Thirdweb (signup required)

---

## Infrastructure

### Running a Node

**Requirements:** Docker, 32 GB RAM, 300 GB storage (mainnet, growing ~1TB/month), 100 Mbps+

```bash
git clone https://github.com/Abstract-Foundation/abstract-node
cd abstract-node/external-node
docker compose --file testnet-external-node.yml up -d
```

**API Access:** HTTP JSON-RPC on port 3060, WebSocket on port 3061

**Monitoring:** Grafana at `http://localhost:3000/d/0/external-node`

The node is a read-replica that fetches data from the Abstract API and re-applies transactions locally. It can verify state locally and serve Web3 API queries but cannot create blocks or generate proofs independently.

**API Namespaces:** `eth_`, `net_`, `web3_`, `debug` (disabled by default), `zks`, `en`

---

## Products

- [Abstract Portal](https://portal.abs.xyz): App discovery layer with streaks, XP, and ecosystem incentives.
- [Abstract Bridge](https://bridge.abs.xyz): Bridge assets from Ethereum and other networks.
- [Block Explorer (Abscan)](https://abscan.org): Transaction explorer and contract verification.
- [AGW MCP Server](https://mcp.abs.xyz/): Model Context Protocol server enabling AI agents to query wallet, chain, and Portal data.
- [Partners](https://abs.xyz/partners): Infrastructure partners including Alchemy, QuickNode, LayerZero, Privy, The Graph, Pyth, MoonPay.
- [Blog](https://blog.abs.xyz): Product updates, ecosystem news, and educational content.
- [FAQ](https://docs.abs.xyz/abstract-global-wallet/frequently-asked-questions): Common questions about AGW.

---

## Community & Social

- [Twitter (@AbstractChain)](https://x.com/AbstractChain): Milestones, thought leadership, announcements.
- [Twitter (@Abstract_Eco)](https://x.com/Abstract_Eco): Builder spotlights, community engagement.
- [Discord](https://discord.com/invite/abstractchain): Community and builder support.
- [GitHub](https://github.com/Abstract-Foundation): Open source repositories and SDKs.
- [YouTube](https://www.youtube.com/@AbstractBlockchain): Tutorials and video content.
- [Events (Luma)](https://lu.ma/abstractchain): Community events.
- [Privacy Policy](https://abs.xyz/privacy-policy)
- [Terms of Service](https://abs.xyz/terms-of-service)