npm package: @ramestta/sdk
Description: Official SDK for interacting with Ramestta Network - L2 Blockchain
Author: Ramestta Tech Team
Latest version: 1.0.0

# @ramestta/sdk

Official JavaScript/TypeScript SDK for interacting with Ramestta Network - **L3 Blockchain**

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

> Forked from Polygon's matic.js and customized for Ramestta Network

## Network Architecture

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

**Important:** All root/bridge contracts are deployed on Polygon L2 (not Ethereum directly).

## Installation

```bash
npm install @ramestta/sdk
# or
yarn add @ramestta/sdk
# or
pnpm add @ramestta/sdk
```

### Web3.js Plugin
```bash
npm install @ramestta/sdk-web3
```

### Ethers.js Plugin
```bash
npm install @ramestta/sdk-ethers
```

## Quick Start

### Using with Ethers.js

```javascript
import { POSClient, use } from "@ramestta/sdk";
import { Web3ClientPlugin } from "@ramestta/sdk-ethers";

// Install ethers plugin
use(Web3ClientPlugin);

const posClient = new POSClient();

await posClient.init({
    network: "mainnet",  // or "testnet"
    version: "v1",
    parent: {
        provider: parentProvider,  // Polygon L2 provider (where root contracts are)
        defaultConfig: {
            from: userAddress
        }
    },
    child: {
        provider: childProvider,   // Ramestta L3 provider
        defaultConfig: {
            from: userAddress
        }
    }
});
```

### Using with Web3.js

```javascript
import { POSClient, use } from "@ramestta/sdk";
import { Web3ClientPlugin } from "@ramestta/sdk-web3";

// Install web3 plugin
use(Web3ClientPlugin);

const posClient = new POSClient();

await posClient.init({
    network: "mainnet",
    version: "v1",
    parent: {
        provider: parentProvider,
        defaultConfig: {
            from: userAddress
        }
    },
    child: {
        provider: childProvider,
        defaultConfig: {
            from: userAddress
        }
    }
});
```

## Network Configuration

### Ramestta Mainnet
- **Chain ID**: 1370
- **RPC URL**: https://blockchain.ramestta.com
- **Explorer**: https://ramascan.com
- **Native Token**: RAMA

### Ramestta Testnet
- **Chain ID**: 1371
- **RPC URL**: https://testnet.ramestta.com
- **Explorer**: https://testnet.ramascan.com

## Features

### ERC20 Token Operations

```javascript
// Get ERC20 token instance
const erc20Token = posClient.erc20('<token-address>', true);  // true for parent chain

// Get balance
const balance = await erc20Token.getBalance(userAddress);
console.log('Balance:', balance);

// Approve
const approveTx = await erc20Token.approve('1000000000000000000');
const txHash = await approveTx.getTransactionHash();
const receipt = await approveTx.getReceipt();

// Deposit (L1 -> L2)
const depositTx = await erc20Token.deposit('1000000000000000000', userAddress);
await depositTx.getReceipt();
```

### MRC20 (Native RAMA Token)

The patched MRC20 contract is deployed at `0x0000000000000000000000000000000000001010`:

```javascript
// Get native RAMA balance on Ramestta
const ramaBalance = await posClient.child.provider.getBalance(userAddress);

// For MRC20 contract operations
const mrc20 = posClient.erc20('0x0000000000000000000000000000000000001010', false);
const balance = await mrc20.getBalance(userAddress);
```

**MRC20 Contract Features (Patched Version):**
- `name()` returns "Ramestta"
- `symbol()` returns "RAMA"
- `decimals()` returns 18
- `totalSupply()` returns 1,000,000,000 RAMA
- `balanceOf(address)` returns native balance
- `transfer(to, value)` - payable transfer
- `withdraw(amount)` - withdraw to L1
- `deposit(user, amount)` - deposit from L1

### ERC721 NFT Operations

```javascript
const erc721Token = posClient.erc721('<token-address>', true);

// Get token balance
const balance = await erc721Token.getBalance(userAddress);

// Approve
const approveTx = await erc721Token.approve(tokenId);

// Deposit NFT (L1 -> L2)
const depositTx = await erc721Token.deposit(tokenId, userAddress);
```

### ERC1155 Operations

```javascript
const erc1155Token = posClient.erc1155('<token-address>', true);

// Get balance
const balance = await erc1155Token.getBalance(userAddress, tokenId);

// Deposit
const depositTx = await erc1155Token.deposit({
    amount: 10,
    tokenId: tokenId,
    userAddress: userAddress
});
```

### Withdraw (L2 -> L1)

Withdrawals from Ramestta to Ethereum require a checkpoint:

```javascript
// Step 1: Initiate withdraw on L2
const erc20Child = posClient.erc20('<token-address>', false);
const withdrawTx = await erc20Child.withdrawStart('1000000000000000000');
const txHash = await withdrawTx.getTransactionHash();

// Step 2: Wait for checkpoint (usually ~30 mins)
const isCheckpointed = await posClient.isCheckPointed(txHash);

// Step 3: Exit on L1
const erc20Parent = posClient.erc20('<token-address>', true);
const exitTx = await erc20Parent.withdrawExit(txHash);
await exitTx.getReceipt();
```

### Check if Exit is Processed

```javascript
const isExited = await erc20Parent.isWithdrawExited(txHash);
console.log('Exit processed:', isExited);
```

## Contract Addresses

### Ramestta Mainnet (Chain ID: 1370)

| Contract | Address |
|----------|---------|
| MRC20 (Native RAMA) | `0x0000000000000000000000000000000000001010` |
| Child Chain | `0x0000000000000000000000000000000000001001` |
| State Receiver | `0x0000000000000000000000000000000000001001` |

### Ethereum Mainnet (Parent Chain)

Contract addresses for the parent chain will be updated after deployment.

## Error Handling

```javascript
try {
    const tx = await erc20Token.deposit(amount, userAddress);
    await tx.getReceipt();
} catch (error) {
    if (error.type === 'insufficient_balance') {
        console.log('Insufficient balance');
    } else if (error.type === 'insufficient_allowance') {
        console.log('Please approve tokens first');
    } else {
        console.error('Transaction failed:', error.message);
    }
}
```

## TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

```typescript
import { POSClient, ERC20, setProofApi } from "@ramestta/sdk";
import type { 
    IPOSClientConfig, 
    ITransactionOption,
    ITransactionWriteResult 
} from "@ramestta/sdk";
```

## Browser Usage

```html
<script src="https://cdn.jsdelivr.net/npm/@ramestta/sdk/dist/ramestta.umd.min.js"></script>
<script>
    const { POSClient } = window.Ramestta;
    // Use SDK...
</script>
```

## Examples

See the [examples](./examples) folder for more detailed usage examples.

## Migration from Polygon matic.js

If you're migrating from Polygon's matic.js:

1. Replace package: `@maticnetwork/maticjs` → `@ramestta/sdk`
2. Update network config to use Ramestta RPC URLs
3. Update contract addresses to Ramestta contracts
4. MRC20 (native token) is at `0x0000000000000000000000000000000000001010`

## API Reference

### POSClient

| Method | Description |
|--------|-------------|
| `init(config)` | Initialize the client |
| `erc20(address, isParent)` | Get ERC20 token instance |
| `erc721(address, isParent)` | Get ERC721 token instance |
| `erc1155(address, isParent)` | Get ERC1155 token instance |
| `isCheckPointed(txHash)` | Check if transaction is checkpointed |
| `isDeposited(txHash)` | Check if deposit is completed |

### ERC20

| Method | Description |
|--------|-------------|
| `getBalance(address)` | Get token balance |
| `getAllowance(address)` | Get allowance for spender |
| `approve(amount)` | Approve tokens |
| `approveMax()` | Approve max tokens |
| `deposit(amount, address)` | Deposit to L2 |
| `withdrawStart(amount)` | Start withdrawal on L2 |
| `withdrawExit(txHash)` | Complete withdrawal on L1 |

## Contributing

Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md).

## License

MIT © [Ramestta Tech Team](https://ramestta.com)

## Links

- [Ramestta Website](https://ramestta.com)
- [RamaScan Explorer](https://ramascan.com)
- [Documentation](https://docs.ramestta.com)
- [GitHub](https://github.com/Ramestta-Blockchain/ramestta-sdk)
- [npm](https://www.npmjs.com/package/@ramestta/sdk)

## Support

- Email: support@ramestta.com
- Discord: [Ramestta Discord](https://discord.gg/ramestta)
- Telegram: [Ramestta Telegram](https://t.me/ramestta)