# FKHood Chain Integration Guide

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

## Build On FKHood

FKHood is an EVM-compatible network designed for applications that need familiar tooling, account-first user experiences, and an upgrade path into the ForkHood 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-fkhood-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 FKHoodLaunch](#integrate-fkhoodlaunch) |
| Build a trading application | [Integrate FKHoodX](#integrate-fkhoodx) |
| 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 | `FKHood Mainnet` | `Forkhood Chain Testnet` |
| Chain ID | `643712891` | `46630` |
| Native currency | `FKHOOD` | `FKHOOD` |
| RPC URL | `https://rpc.forkhood.xyz` | `https://www.forkhood.xyz/forkhood-rpc` |
| Block explorer | `https://scan.forkhood.xyz` | `TBD` |
| WebSocket RPC | `wss://rpc.forkhood.xyz/ws` | `TBD` |

Create a local configuration file from the following template:

```bash
# .env.local
FKHOOD_CHAIN_ID=643712891
FKHOOD_RPC_URL=https://rpc.forkhood.xyz
FKHOOD_EXPLORER_URL=https://scan.forkhood.xyz
FKHOOD_CONFIRMATIONS=1
FKHOOD_NETWORK_ACTIVE=false
```

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

## Add FKHood To A Wallet

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

```ts
const fkhoodChainId = 643712891;
const rpcUrl = process.env.FKHOOD_RPC_URL;
const explorerUrl = process.env.FKHOOD_EXPLORER_URL;

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

await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: `0x${fkhoodChainId.toString(16)}`,
    chainName: 'FKHood Mainnet',
    nativeCurrency: {
      name: 'FKHOOD',
      symbol: 'FKHOOD',
      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 fkhoodChainId = 643712891;
const rpcUrl = process.env.FKHOOD_RPC_URL;
if (!rpcUrl) throw new Error('FKHOOD_RPC_URL is required');

export const fkhood = {
  id: fkhoodChainId,
  name: 'FKHood Mainnet',
  nativeCurrency: { name: 'FKHOOD', symbol: 'FKHOOD', decimals: 18 },
  rpcUrls: {
    default: { http: [rpcUrl] },
  },
};

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

### ethers

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

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

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

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

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

const network = await provider.getNetwork();

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

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

FKHood 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 "$FKHOOD_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: {
    fkhood: {
      url: process.env.FKHOOD_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 Forkhood 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 FKHoodLaunch

FKHoodLaunch is the native token creation and fair-launch surface for ForkHood. 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 FKHoodX

FKHoodX 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 FKHoodX SDK will define supported order types, margin modes, price feeds, liquidation behavior, and event schemas.

## Integrate FKHoodForecast

FKHoodForecast 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 FKHood 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:

- [ ] ForkHood 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 ForkHood 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.