npm package: @ramestta/sdk-react
Description: React hooks and components for @ramestta/sdk - Ramestta Network L3 Blockchain
Author: Ramestta Tech Team
Latest version: 1.0.0

# @ramestta/sdk-react

[![npm version](https://badge.fury.io/js/@ramestta%2Fsdk-react.svg)](https://badge.fury.io/js/@ramestta%2Fsdk-react)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

React hooks and components for `@ramestta/sdk` - Official SDK for Ramestta Network L3 Blockchain.

## Network Architecture

```
L1: Ethereum (Root Chain)
     ↓
L2: Polygon (Parent Chain) - Root contracts deployed here
     ↓
L3: Ramestta (Child Chain) - Application chain
```

## Installation

```bash
npm install @ramestta/sdk @ramestta/sdk-react @ramestta/sdk-ethers ethers react
```

## Quick Start

### Setup Provider

```tsx
import React from 'react';
import { RamesttaProvider } from '@ramestta/sdk-react';
import { Web3ClientPlugin } from '@ramestta/sdk-ethers';
import { ethers } from 'ethers';

const parentProvider = new ethers.providers.JsonRpcProvider('https://polygon-rpc.com');
const childProvider = new ethers.providers.JsonRpcProvider('https://blockchain.ramestta.com');

function App() {
  return (
    <RamesttaProvider
      config={{
        network: 'mainnet',
        parentProvider,
        childProvider,
        defaultAccount: '0xYourAddress',
      }}
      plugin={Web3ClientPlugin}
    >
      <YourApp />
    </RamesttaProvider>
  );
}
```

### Use Hooks

```tsx
import { 
  useRamestta, 
  useTokenBalance, 
  useDeposit, 
  useWithdrawStart,
  useIsCheckpointed,
  MRC20_ADDRESS 
} from '@ramestta/sdk-react';

function WalletInfo() {
  const { isInitialized, account, error } = useRamestta();
  const { balance, isLoading } = useTokenBalance(MRC20_ADDRESS, account);

  if (!isInitialized) return <div>Initializing...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <p>Account: {account}</p>
      <p>RAMA Balance: {isLoading ? 'Loading...' : balance}</p>
    </div>
  );
}
```

## Available Hooks

### Core Hooks

| Hook | Description |
|------|-------------|
| `useRamestta()` | Main hook - returns client, account, initialization state |
| `usePOSClient()` | Get the POSClient instance directly |
| `useIsReady()` | Check if SDK is initialized and ready |
| `useAccount()` | Get/set current account |
| `useNetwork()` | Get network information |

### Token Hooks

| Hook | Description |
|------|-------------|
| `useERC20(address, isParent)` | Get ERC20 token instance |
| `useERC721(address, isParent)` | Get ERC721 NFT instance |
| `useERC1155(address, isParent)` | Get ERC1155 token instance |
| `useTokenBalance(address, user, isParent)` | Get token balance with loading state |
| `useRAMABalance(user)` | Get native RAMA balance |

### Transaction Hooks

| Hook | Description |
|------|-------------|
| `useApprove(tokenAddress, isParent)` | Approve token spending |
| `useDeposit(tokenAddress)` | Deposit tokens (L2 → L3) |
| `useWithdrawStart(tokenAddress)` | Start withdrawal (L3 → L2) |
| `useWithdrawExit(tokenAddress)` | Complete withdrawal exit |
| `useIsCheckpointed(txHash)` | Check if tx is checkpointed |

## Examples

### Token Approval and Deposit

```tsx
import { useApprove, useDeposit } from '@ramestta/sdk-react';

function DepositForm({ tokenAddress }) {
  const { approve, status: approveStatus } = useApprove(tokenAddress, true);
  const { deposit, status: depositStatus, hash } = useDeposit(tokenAddress);
  const [amount, setAmount] = useState('');

  const handleDeposit = async () => {
    // First approve
    await approve(amount);
    // Then deposit
    await deposit(amount, userAddress);
  };

  return (
    <div>
      <input 
        value={amount} 
        onChange={(e) => setAmount(e.target.value)} 
        placeholder="Amount"
      />
      <button onClick={handleDeposit} disabled={approveStatus === 'pending'}>
        {approveStatus === 'pending' ? 'Approving...' : 
         depositStatus === 'pending' ? 'Depositing...' : 'Deposit'}
      </button>
      {hash && <p>Transaction: {hash}</p>}
    </div>
  );
}
```

### Withdrawal Flow

```tsx
import { useWithdrawStart, useWithdrawExit, useIsCheckpointed } from '@ramestta/sdk-react';

function WithdrawFlow({ tokenAddress }) {
  const { withdrawStart, hash: burnHash, status: burnStatus } = useWithdrawStart(tokenAddress);
  const { withdrawExit, status: exitStatus } = useWithdrawExit(tokenAddress);
  const { isCheckpointed, isLoading: checkingCheckpoint } = useIsCheckpointed(burnHash);

  return (
    <div>
      {/* Step 1: Start withdrawal */}
      <button onClick={() => withdrawStart('1000000000000000000')}>
        Start Withdraw
      </button>
      
      {/* Step 2: Wait for checkpoint */}
      {burnHash && (
        <div>
          <p>Burn TX: {burnHash}</p>
          <p>Checkpointed: {checkingCheckpoint ? 'Checking...' : isCheckpointed ? 'Yes ✓' : 'No (wait ~30 min)'}</p>
        </div>
      )}
      
      {/* Step 3: Exit on L2 */}
      {isCheckpointed && (
        <button onClick={() => withdrawExit(burnHash)}>
          Complete Exit
        </button>
      )}
    </div>
  );
}
```

## Constants

```tsx
import { 
  RAMESTTA_MAINNET,
  RAMESTTA_TESTNET,
  POLYGON_MAINNET,
  MRC20_ADDRESS 
} from '@ramestta/sdk-react';

// RAMESTTA_MAINNET = { chainId: 1370, rpcUrl: 'https://blockchain.ramestta.com', ... }
// RAMESTTA_TESTNET = { chainId: 1371, rpcUrl: 'https://testnet.ramestta.com', ... }
// POLYGON_MAINNET = { chainId: 137, rpcUrl: 'https://polygon-rpc.com' }
// MRC20_ADDRESS = '0x0000000000000000000000000000000000001010'
```

## TypeScript Support

Full TypeScript support with exported types:

```tsx
import type { 
  RamesttaConfig,
  RamesttaContextValue,
  TokenBalance,
  TransactionState 
} from '@ramestta/sdk-react';
```

## Related Packages

- [@ramestta/sdk](https://www.npmjs.com/package/@ramestta/sdk) - Core SDK
- [@ramestta/sdk-ethers](https://www.npmjs.com/package/@ramestta/sdk-ethers) - Ethers.js plugin
- [@ramestta/sdk-web3](https://www.npmjs.com/package/@ramestta/sdk-web3) - Web3.js plugin

## Documentation

For full documentation, visit [https://docs.ramestta.com](https://docs.ramestta.com)

## License

MIT