### Next.js Integration Example

Source: https://docs.caldera.xyz/metalayer/developers/widget/quickstart

A comprehensive Next.js example demonstrating the integration of the Metalayer Widget with wagmi, RainbowKit, and React Query. This setup includes wallet connection and essential configurations.

```typescript
import { WidgetProvider, Widget } from '@metalayer/widget';
import { METALAYER_TESTNETS } from '@metalayer/viem-chains';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WagmiProvider, createConfig, http } from 'wagmi';
import type { Chain } from 'viem/chains';
// Import RainbowKit components and styles
// Note: You can replace RainbowKit with any other wagmi/viem compatible wallet connector
import { RainbowKitProvider, ConnectButton, useConnectModal, getDefaultConfig } from '@rainbow-me/rainbowkit';

// Import required styles (order matters for proper styling)
import '@metalayer/widget/styles.css';
import '@rainbow-me/rainbowkit/styles.css';
import 'material-symbols/rounded.css';

// Create wagmi config with RainbowKit 
// Note: This configuration can be replaced with any other wagmi/viem based wallet solution
const config = getDefaultConfig({
  appName: 'Metalayer Bridge Widget Example',
  projectId: 'YOUR_WALLETCONNECT_PROJECT_ID', // Get one at https://cloud.reown.com/
  chains: [...METALAYER_TESTNETS as unknown as readonly [Chain, ...Chain[]]],
});

const queryClient = new QueryClient();

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {/* RainbowKit provider can be replaced with your preferred wallet connector */}
        <RainbowKitProvider>
          <WidgetProvider
            sdkConfig={{
              apiKey: 'your-api-key',
              environment: 'development',
            }}
            onError={(error) => {
              console.error('Widget error:', error);
              // Use your preferred toast library
              // toast.error(error.message);
            }}
          >
            <Page />
          </WidgetProvider>
        </RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

function Page() {
  // Using RainbowKit's ConnectButton to handle wallet connection
  // This can be replaced with any other wallet connection UI
  const { openConnectModal } = useConnectModal();
  
  return (
    <div className="app">
      <header>
        {/* ConnectButton can be replaced with your preferred wallet connection UI */}
        <ConnectButton />
      </header>
      <main>
        <Widget config={{ onOpenConnectModal: openConnectModal }} />
      </main>
    </div>
  );
}

```

--------------------------------

### Install Core Dependencies

Source: https://docs.caldera.xyz/metalayer/developers/widget/quickstart

Install the essential npm packages required for the Metalayer Widget, including state management, UI libraries, and blockchain utilities.

```bash
pnpm add @metalayer/viem-chains @tanstack/react-query react react-dom viem@2.x wagmi material-symbols
```

--------------------------------

### Install RainbowKit for Wallet Integration

Source: https://docs.caldera.xyz/metalayer/developers/widget/quickstart

Optionally install RainbowKit if you plan to integrate wallet connection functionality. This package provides a pre-built UI for wallet management.

```bash
pnpm add @rainbow-me/rainbowkit
```

--------------------------------

### Install Metalayer Widget Package

Source: https://docs.caldera.xyz/metalayer/developers/widget/quickstart

Install the Metalayer Widget using your preferred package manager. This command adds the core widget library to your project dependencies.

```bash
pnpm add @metalayer/widget
# or
npm install @metalayer/widget 
# or
yarn add @metalayer/widget
```

--------------------------------

### React Hooks Setup

Source: https://docs.caldera.xyz/metalayer/developers/token-bridging/setup

Shows how to set up React hooks for the SDK by wrapping your application with MetaRouterProvider and QueryClientProvider. This requires installing `@tanstack/react-query`.

```typescript
import { MetaRouterProvider } from '@metalayer/sdk';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

const App = () => {
  return (
    <QueryClientProvider client={queryClient}>
      <MetaRouterProvider
        queryClient={queryClient}
        config={{
          apiKey: 'test-api-key', // Replace with your API key
          environment: 'development',
        }}
      >
          <GetQuotes />
      </MetaRouterProvider>
    </QueryClientProvider>
  );
};
```

--------------------------------

### WidgetProvider Configuration

Source: https://docs.caldera.xyz/metalayer/developers/widget/quickstart

Configure the WidgetProvider with your SDK API key and environment. Implement an onError callback for handling widget-related errors.

```typescript
<WidgetProvider
  // Required
  sdkConfig={{
    apiKey: "your-api-key",
    environment: "development", // "production" or "staging"
  }}
  // Optional error handling
  onError={(error) => {
    console.error('Widget error:', error);
  }}
/>
```

--------------------------------

### Install @metalayer/sdk

Source: https://docs.caldera.xyz/metalayer/developers/token-bridging/setup

Installs the @metalayer/sdk package using common package managers like pnpm, npm, or yarn. This is the first step to integrate the SDK into your project.

```bash
pnpm add @metalayer/sdk 
or
npm install @metalayer/sdk 
or
yarn add @metalayer/sdk
```

--------------------------------

### Install Hardhat (Bash)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/hardhat

Installs the Hardhat development environment as a project dependency. Hardhat provides tools for compiling, deploying, and testing smart contracts.

```bash
npm install hardhat
```

--------------------------------

### Basic Widget Integration

Source: https://docs.caldera.xyz/metalayer/developers/widget/quickstart

Integrate the Metalayer Widget into your React application by wrapping it with the WidgetProvider. Configure the widget with an optional callback for opening the wallet connection modal.

```typescript
<Widget
  config={{
    onOpenConnectModal: openConnectModal // Function to open wallet connection modal
  }}
/>
```

--------------------------------

### Import Required CSS

Source: https://docs.caldera.xyz/metalayer/developers/widget/quickstart

Import the necessary CSS files for the Metalayer Widget and optional integrations like RainbowKit. Ensure correct order for proper styling.

```typescript
import '@metalayer/widget/styles.css';
import '@rainbow-me/rainbowkit/styles.css'; // If using RainbowKit
import 'material-symbols/rounded.css'; // Temporary icon dependency
```

--------------------------------

### Install Foundry (Windows)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/foundry

Installs the Foundry development toolchain on Windows systems by first setting up Rust and then installing the foundry-cli and anvil binaries.

```shell
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs/ | sh
cargo install --git https://github.com/foundry-rs/foundry foundry-cli anvil --bins --locked
```

--------------------------------

### Install Ethers Plugin (Bash)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/hardhat

Installs the Hardhat Ethers plugin and the Ethers.js library. The Ethers plugin enables interaction with Ethereum networks using Ethers.js within Hardhat.

```bash
npm install @nomiclabs/hardhat-ethers ethers
```

--------------------------------

### Create Hardhat Project Directory (Bash)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/hardhat

Initializes a new directory for your Hardhat project and navigates into it. This is the first step in setting up a new smart contract development environment.

```bash
mkdir hardhat && cd hardhat
```

--------------------------------

### Initialize npm Project (Bash)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/hardhat

Initializes a new Node.js project by creating a package.json file. This file manages project dependencies and scripts.

```bash
npm init -y
```

--------------------------------

### Create Scripts Directory (Bash)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/hardhat

Creates a 'scripts' directory to house deployment and task execution scripts. It then navigates into this new directory.

```bash
mkdir scripts && cd scripts
```

--------------------------------

### Install Foundry (Linux/macOS)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/foundry

Installs the Foundry development toolchain on Linux or macOS systems using a curl script and the foundryup command.

```shell
curl -L https://foundry.paradigm.xyz | bash
foundryup
```

--------------------------------

### Compile Smart Contracts (Bash)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/hardhat

Compiles all the Solidity smart contracts in the 'contracts' directory. This step generates the contract artifacts needed for deployment.

```bash
npx hardhat compile
```

--------------------------------

### Initialize MetaRouterClient

Source: https://docs.caldera.xyz/metalayer/developers/token-bridging/setup

Demonstrates how to initialize the MetaRouterClient with your API key and environment. The client is used to interact with routing services and retrieve quotes.

```typescript
import { MetaRouterClient } from '@metalayer/sdk';

const router = MetaRouterClient.init({
  apiKey: 'your-api-key',
  environment: 'development',
  defaultOptions: {
    quotePreference: 'bestReturn',
  },
});

// Get a quote
const quote = await router.quote({
  // ...quote params
});
```

--------------------------------

### Create Hardhat Project CLI (Bash)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/hardhat

Uses the Hardhat command-line interface to set up a new Hardhat project structure. This command prompts for project type and dependencies.

```bash
npx hardhat
```

--------------------------------

### Create Contract File (Bash)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/hardhat

Creates an empty Solidity file named 'your_contract.sol' within the 'contracts' directory. This file will contain your smart contract code.

```bash
touch your_contract.sol
```

--------------------------------

### Install OpenZeppelin Contracts

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/foundry

Adds the OpenZeppelin Contracts library as a dependency to the Foundry project, enabling the use of secure, audited smart contract components.

```shell
forge install OpenZeppelin/openzeppelin-contracts
```

--------------------------------

### Run Deployment Script (Bash)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/hardhat

Executes the deployment script using Hardhat, specifying the target network ('caldera' in this case). This command initiates the contract deployment process.

```bash
npx hardhat run scripts/deploy.js --network caldera
```

--------------------------------

### Create Deployment Script (Bash)

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/hardhat

Creates an empty JavaScript file named 'deploy.js' within the 'scripts' directory. This file will contain the logic for deploying your smart contract.

```bash
touch deploy.js
```

--------------------------------

### Sample Solidity Contract

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/foundry

A basic Solidity contract named HelloWorld that stores and returns a greeting string. It specifies the compiler version requirement.

```solidity
// SPDX-License-Identifier: MIT
// compiler version must be greater than or equal to 0.8.17 and less than 0.9.0
pragma solidity ^0.8.17;

contract HelloWorld {
    string public greet = "Hello World!";
}
```

--------------------------------

### useQuote Hook Detailed Example

Source: https://docs.caldera.xyz/metalayer/developers/token-bridging/methods

Provides a detailed example of the `useQuote` React hook for querying USDC quotes between Ethereum Sepolia and Manta Sepolia. It illustrates passing specific chain IDs, token addresses, amount, and sender address.

```TypeScript
import { useQuote } from '@metalayer/sdk';

export const YourApp = () => {
    const {
        data: quotesData,
        quote: bestQuote,
        quotes,
        isLoading: isQuotesLoading,
        refreshIn,
        } = useQuote({
        chainInId: 11155111, // Ethereum Sepolia
        chainOutId: 3441006, // Manta Sepolia
        tokenInAddress: '0x763f6173B36b28d29e8FF3400490Fd1990b1d1C9', // USDC
        tokenOutAddress: '0x0652aEc2DeE0Fee9D05E614c95Ce8A01a7336cD8', // USDC
        amount: BigInt('1'), // 1 USDC
        senderAddress: '0x0000000000000000000000000000000000000000',
    });
}

```

--------------------------------

### Quick-Start: Run Metalayer Validator with Docker

Source: https://docs.caldera.xyz/metalayer/developers/validators/running

This bash script demonstrates the quick-start process for running a Metalayer validator. It includes steps to download a chain configuration file, pull the necessary Docker image, and run the validator container with specified configurations and environment variables.

```bash
# 1  Get our chain config bundle (replace link when public)
wget https://docs.metalayer.xyz/configs/<version>/ethereum.yaml -O ethereum.yaml

# 2  Pull the Abacus Works agent image
docker pull --platform linux/amd64 gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0

# 3  Run the validator (example for Ethereum mainnet)
docker run -it --rm \
  -v $(pwd)/ethereum.yaml:/config/validator.yaml:ro \
  -v $(pwd)/data:/metalayer_db \
  -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \
  gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0 \
  validator --config /config/validator.yaml
```

--------------------------------

### Solidity Hello World Contract

Source: https://docs.caldera.xyz/rollup-engine/deploying-contracts/remix

A basic Solidity smart contract named HelloWorld. It declares a public string variable 'greet' initialized to 'Hello World!'. The contract requires a Solidity compiler version greater than or equal to 0.8.17 and less than 0.9.0.

```solidity
// SPDX-License-Identifier: MIT
// compiler version must be greater than or equal to 0.8.17 and less than 0.9.0
pragma solidity ^0.8.17;

contract HelloWorld {
    string public greet = "Hello World!";
}
```