# RobinFork Chain Integration Guide

> Status: Pre-mainnet - configuration assigned, activation pending
>
> RobinFork Mainnet is not live yet. The network identifiers and planned `RobinFork.xyz` endpoints are listed below; protocol contract addresses, SDK package names, and service activation remain `TBD` until release. Do not enable production writes until RobinFork publishes an explicit Mainnet activation notice and your RPC verifies the expected chain ID.

## Build On RobinFork

RobinFork is an EVM-compatible network designed for applications that need familiar tooling, account-first user experiences, and an upgrade path into the RobinFork ecosystem.

This guide helps teams prepare an integration before Mainnet launch. It uses `viem`, `ethers`, Foundry, and standard JSON-RPC conventions, so existing EVM applications can adapt without changing their core contract model.

## Integration At A Glance

| You want to | Start here |
| --- | --- |
| Connect a wallet | [Add the network](#add-robinfork-to-a-wallet) |
| Read chain data | [Connect through RPC](#connect-through-rpc) |
| Deploy a contract | [Deploy a contract](#deploy-a-contract) |
| Launch a community token | [Integrate RobinForkLaunch](#integrate-robinforklaunch) |
| Build a trading application | [Integrate RobinForkX](#integrate-robinforkx) |
| Prepare for release | [Use the launch checklist](#mainnet-launch-checklist) |

## Network Configuration

Use environment variables for all network parameters. The identifiers below are the intended production configuration, not evidence that public RPC, explorer, or WebSocket services are currently live.

| Parameter | Mainnet | Testnet |
| --- | --- | --- |
| Network name | `RobinFork Mainnet` | `RobinFork Chain Testnet` |
| Chain ID | `643712891` | `46630` |
| Native currency | `FRB` | `FRB` |
| RPC URL | `https://rpc.RobinFork.xyz` | `https://RobinFork.xyz/robinfork-rpc` |
| Block explorer | `https://scan.RobinFork.xyz` | `TBD` |
| WebSocket RPC | `wss://rpc.RobinFork.xyz/ws` | `TBD` |

Create a local configuration file from the following template:

```bash
# .env.local
ROBINFORK_CHAIN_ID=643712891
ROBINFORK_RPC_URL=https://rpc.RobinFork.xyz
ROBINFORK_EXPLORER_URL=https://scan.RobinFork.xyz
ROBINFORK_CONFIRMATIONS=1
ROBINFORK_NETWORK_ACTIVE=false
```

Never commit production RPC credentials, deployer private keys, or API secrets.

## Add RobinFork To A Wallet

Ask users to add RobinFork only after the Mainnet activation notice is published. The following request works with EIP-1193 compatible wallets.

```ts
const robinForkChainId = 643712891;
const rpcUrl = process.env.ROBINFORK_RPC_URL;
const explorerUrl = process.env.ROBINFORK_EXPLORER_URL;

if (!rpcUrl || !explorerUrl) throw new Error('Missing RobinFork network configuration');

await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: `0x${robinForkChainId.toString(16)}`,
    chainName: 'RobinFork Mainnet',
    nativeCurrency: {
      name: 'FRB',
      symbol: 'FRB',
      decimals: 18,
    },
    rpcUrls: [rpcUrl],
    blockExplorerUrls: [explorerUrl],
  }],
});
```

Your interface should always show the active network, make switching networks explicit, and handle rejected wallet requests without blocking the rest of the app.

## Connect Through RPC

### viem

```ts
import { createPublicClient, http } from 'viem';

const robinForkChainId = 643712891;
const rpcUrl = process.env.ROBINFORK_RPC_URL;
if (!rpcUrl) throw new Error('ROBINFORK_RPC_URL is required');

export const robinfork = {
  id: robinForkChainId,
  name: 'RobinFork Mainnet',
  nativeCurrency: { name: 'FRB', symbol: 'FRB', decimals: 18 },
  rpcUrls: {
    default: { http: [rpcUrl] },
  },
};

export const publicClient = createPublicClient({
  chain: robinfork,
  transport: http(rpcUrl),
});
```

### ethers

```ts
import { JsonRpcProvider } from 'ethers';

const robinForkChainId = 643712891;
const rpcUrl = process.env.ROBINFORK_RPC_URL;
if (!rpcUrl) throw new Error('ROBINFORK_RPC_URL is required');

export const provider = new JsonRpcProvider(
  rpcUrl,
  robinForkChainId,
);
```

Before enabling a production flow, verify the RPC response matches your expected chain ID:

```ts
if (process.env.ROBINFORK_NETWORK_ACTIVE !== 'true') {
  throw new Error('RobinFork Mainnet is not active');
}

const network = await provider.getNetwork();

if (network.chainId !== BigInt(643712891)) {
  throw new Error('Connected RPC is not RobinFork');
}
```

## Transaction Lifecycle

Treat a broadcast transaction as pending until it has the confirmation depth required by your application.

1. Simulate the transaction when your client supports it.
2. Ask the wallet to sign and broadcast only after the user has reviewed the action.
3. Store the transaction hash immediately after broadcast.
4. Wait for the configured confirmation threshold.
5. Read the receipt and check `status` before marking the action successful.

```ts
const hash = await walletClient.writeContract(request);
const confirmations = Number(process.env.ROBINFORK_CONFIRMATIONS ?? 1);
const receipt = await publicClient.waitForTransactionReceipt({ hash, confirmations });

if (receipt.status !== 'success') {
  throw new Error(`Transaction reverted: ${hash}`);
}
```

Do not infer success from a wallet popup closing or a transaction hash existing in local state.

## Deploy A Contract

RobinFork is designed for standard EVM bytecode. Existing Solidity contracts should compile with your current toolchain unless they depend on chain-specific opcode behavior or external infrastructure.

### Foundry

```bash
forge script script/Deploy.s.sol:Deploy \
  --rpc-url "$ROBINFORK_RPC_URL" \
  --private-key "$DEPLOYER_PRIVATE_KEY" \
  --broadcast
```

Run explorer verification only after the official verifier integration is live. Keep the deployer key in a dedicated signing system; avoid placing long-lived private keys in shell history or CI logs.

### Hardhat

```ts
// hardhat.config.ts
export default {
  solidity: '0.8.24',
  networks: {
    robinfork: {
      url: process.env.ROBINFORK_RPC_URL,
      chainId: 643712891,
      accounts: process.env.DEPLOYER_PRIVATE_KEY ? [process.env.DEPLOYER_PRIVATE_KEY] : [],
    },
  },
};
```

Before a Mainnet deployment, run your full test suite against the official RobinFork Chain Testnet and record:

- compiler version and optimizer settings;
- constructor parameters;
- deployed bytecode hash;
- admin, owner, and multisig addresses;
- verified source location.

## Token Contract Requirements

For an ERC-20 style token, publish the following information before requesting ecosystem integration:

| Requirement | What to publish |
| --- | --- |
| Identity | Token name, symbol, decimals, and contract address |
| Supply | Initial supply, minting policy, and burn policy |
| Control | Owner, multisig, timelock, and upgrade authority |
| Distribution | Team allocation, vesting schedule, and community allocation |
| Risk | Audit status, known limitations, and official communication channels |

Avoid hidden transfer taxes, unrestricted mint functions, ambiguous owner permissions, or transfer behavior that differs from the token documentation.

## Integrate RobinForkLaunch

RobinForkLaunch is the native token creation and fair-launch surface for RobinFork. The public contract addresses and SDK package names are `TBD` until Mainnet launch.

Prepare your application with a launch configuration object rather than hard-coding UI state:

```ts
type LaunchConfig = {
  name: string;
  symbol: string;
  totalSupply: bigint;
  creatorAllocationBps: number;
  vestingMonths: number;
  mintable: boolean;
  metadataURI?: string;
};
```

Before calling a production launch method, validate that:

1. `creatorAllocationBps` is between `0` and `10_000`.
2. Allocation, vesting, and minting details are shown to the user in plain language.
3. Token metadata is immutable or has an explicit update policy.
4. The creator has acknowledged the launch terms.

## Integrate RobinForkX

RobinForkX will provide a fully onchain perpetuals trading venue. Until its protocol interfaces are published, treat the following as integration principles rather than final ABI specifications.

- Read market configuration from contracts, not from a static frontend list.
- Quote margin, funding, and liquidation risk before the user signs.
- Use fixed-point integers for monetary values; never use JavaScript floating-point arithmetic for settlement logic.
- Keep order state, fill state, and receipt state separate in your UI.
- Display the contract address and market identifier for every position.

The published RobinForkX SDK will define supported order types, margin modes, price feeds, liquidation behavior, and event schemas.

## Integrate RobinForkForecast

RobinForkForecast will provide prediction markets for verifiable outcomes. Applications should present the market question, resolution source, resolution deadline, and settlement state before a user participates.

For each market, make these fields visible:

```ts
type ForecastMarket = {
  marketId: bigint;
  question: string;
  outcomes: string[];
  resolutionSource: string;
  resolutionTime: bigint;
  status: 'open' | 'locked' | 'resolved' | 'disputed';
};
```

Never represent an unresolved market as settled, and preserve a visible path to the official resolution source.

## Reliability And Error Handling

Build for normal failure states from the beginning.

| Situation | Expected application behavior |
| --- | --- |
| Wallet rejected request | Keep the user on the current screen and explain that no transaction was submitted. |
| RPC timeout | Retry a read with bounded backoff; never blindly retry a write. |
| Transaction replaced | Track the replacement hash and update the pending state. |
| Receipt reverted | Show the failed status and a link to the explorer once available. |
| Wrong network | Offer an explicit RobinFork network switch action. |

For write requests, preserve enough context to let a user retry safely: the intended contract, function, parameters, and latest simulation result.

## Mainnet Launch Checklist

Before turning on Mainnet access, confirm all of the following:

- [ ] RobinFork has announced Mainnet activation and the RPC returns Chain ID `643712891`.
- [ ] Public RPC, WebSocket, explorer, and verifier services have passed availability checks.
- [ ] Wallet network switching has been tested with supported wallet providers.
- [ ] Contracts have been deployed from the approved multisig or deployer address.
- [ ] Contract source and constructor parameters are verified on the official explorer.
- [ ] Read and write RPC failure states have been tested.
- [ ] Transaction receipts are required before success is shown.
- [ ] Token authority and distribution information are visible to users.
- [ ] Production monitoring and incident contacts are in place.

## Support And Release Notes

Publish integration notices with the date, environment, affected contract addresses, and required developer action. For security-sensitive changes, communicate through the official RobinFork channels only.

When protocol contract addresses and SDK package names are published, replace the remaining `TBD` values in this guide and issue a versioned release note.