# AllenHark Relay — Customer Integration Guide

## Introduction

AllenHark Relay is an institutional-grade Solana transaction relay designed for high-frequency traders, market makers, and automated systems requiring **sub-millisecond dispatch**. By bypassing the public mempool and routing directly to leaders, we offer superior speed and MEV protection.

**Key Features:**
*   **0-Slot Execution**: Transactions land in the same slot they are sent.
*   **0-Hop Delivery**: Direct connections to current and upcoming leaders.
*   **MEV Protection**: Private transaction routing prevents front-running.
*   **QUIC & HTTPS Support**: Optimized endpoints for every use case.

---

## Connectivity

We provide two primary submission modes. **QUIC is strongly recommended** for production use due to its performance benefits (up to 80% latency reduction).

### 1. QUIC Endpoint (Recommended)
*   **Domain:** `84.32.223.83`
*   **Port:** `4433`
*   **Protocol:** QUIC (UDP)
*   **Latency:** ~0.1ms (internal processing)
*   **Features:** Persistent connections, multiplexing, 0-RTT resumption.

### 2. HTTPS Endpoint (Fallback)
*   **URL:** `https://relay.allenhark.com/v1/sendTx`
*   **Method:** `POST`
*   **Latency:** ~1–5ms (due to TCP/TLS overhead)

---

## Authentication

All requests require an API Key. You can pass this via a header (recommended) or a query parameter.

**Header Method:**
`x-api-key: YOUR_API_KEY`

**Query Parameter Method:**
`?api-key=YOUR_API_KEY`

---

## Tip Requirements

To ensure priority processing and prevent spam, every transaction **must include a transfer instruction** (tip) to one of our designated tip wallets.

**Minimum Tip:** `0.001 SOL` (1,000,000 lamports)

**Tip Wallets (Select one randomly per transaction):**
```
hark1zxc5Rz3K8Kquz79WPWFEgNCFeJnsMJ16f22uNP
harkm2BTWxZuszoNpZnfe84jRbQTg6KGHaQBmWzDGQQ
hark4CwtTnN2y9FaxjcFBAJdJqQrpouu5pgEixfqdEz
harkoJfnM6dxrJydx5eVmDVwAgwC94KbhuxF69UbXwP
hark6hUDUTekc1DGxWdJcuyDZwf6pJdCxd4SXAVtta6
harkoTvFpKSrEQduYrNHXCurARVT19Ud3BnFhVxabos
harkEpXoJv5qVzHaN7HSuUAd6PHjyMcFMcDYBMDJCEQ
harkyXDdZSoJGyCxa24t2QXx1poPyp8YfghbtpzGSzK
harkR2YJ4Dpt4UDJTcBirjnSPBhNpQFcoFkNpCkVqNk
harkRBygM8pHYe4K8eBjfxyEX19oJn3LepFjvNbLbyi
harkYFxB6DuUFNwDLvA5CQ66KpfRvFgUoVypMagNcmd
```

---

## Integration Examples

### 1. JavaScript / TypeScript (HTTPS)

```javascript
// Using fetch for HTTPS submission
const response = await fetch("https://relay.allenhark.com/v1/sendTx", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    tx: "BASE64_ENCODED_TRANSACTION_STRING", // Your signed transaction
    simulate: false // Must be false
  })
});

const result = await response.json();
console.log(result);
// Success: { "status": "accepted", "request_id": "..." }
// Error: { "status": "error", "code": "tip_missing", "message": "..." }
```

### 2. Rust (QUIC via Quinn)

```rust
use quinn::{ClientConfig, Endpoint};
use rustls::RootCertStore;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Configure TLS (System Roots)
    let mut roots = RootCertStore::empty();
    roots.add_trust_anchors(webpki_roots::TLS_SERVER_ROOTS.iter().map(|ta| {
        rustls::OwnedTrustAnchor::from_subject_spki_name_constraints(
            ta.subject, ta.spki, ta.name_constraints,
        )
    }));
    let client_config = ClientConfig::with_root_certificates(roots);
    
    // 2. Connect
    let mut endpoint = Endpoint::client("0.0.0.0:0".parse()?)?;
    endpoint.set_default_client_config(client_config);
    let conn = endpoint.connect("relay.allenhark.com:4433".parse()?, "relay.allenhark.com")?.await?;
    
    // 3. Open Stream & Send
    let (mut send, mut recv) = conn.open_bi().await?;
    
    // Protocol: API Key line -> JSON Payload
    send.write_all(b"api-key: YOUR_API_KEY\n").await?;
    let payload = serde_json::json!({
        "tx": "BASE64_ENCODED_TX",
        "simulate": false
    });
    send.write_all(&serde_json::to_vec(&payload)?).await?;
    send.finish().await?;
    
    // 4. Read Response
    let response = recv.read_to_end(4096).await?;
    println!("Response: {}", String::from_utf8_lossy(&response));
    
    Ok(())
}
```

---

## Response Codes

| Status | Code | Meaning |
|:-------|:-----|:--------|
| `200 OK` | `accepted` | Transaction received and queued for broadcast. |
| `400 Bad Request` | `tip_missing` | No transfer to an AllenHark wallet found. |
| `400 Bad Request` | `tip_insufficient` | Tip is below 0.001 SOL. |
| `400 Bad Request` | `simulate_forbidden` | `simulate` parameter was set to `true`. |
| `401 Unauthorized` | `invalid_api_key` | API Key is missing or invalid. |
| `429 Too Many Requests` | `rate_limit_exceeded`| You have exceeded your plan's limits. |

---

## Detailed Q&A

### Troubleshooting & Common Issues

**Q: Why am I receiving a `tip_missing` error?**
A: This error occurs when our validation engine cannot find a transfer instruction to one of our designated tip wallets in your transaction.

*   **Check 1:** Ensure you are using the list of wallets provided above. Using an old or incorrect wallet address will fail validation.
*   **Check 2:** Verify the transfer amount. It must be at least 1,000,000 lamports (0.001 SOL). Values like 0.0009 SOL will trigger `tip_insufficient`.
*   **Check 3:** Ensure the transfer instruction is at the top level of the transaction, not nested deeply in a CPI (Cross-Program Invocation) where static analysis might miss it.

**Q: Can I simulate transactions?**
A: **No.** The `simulate` flag is explicitly forbidden (`simulate_forbidden`). AllenHark Relay is a pure propagation engine. For simulation, please use a standard RPC provider like Helius or QuickNode. We optimize purely for "fire-and-forget" speed.

**Q: My transactions are accepted but not landing. Why?**
A: If you receive a `200 OK` with `accepted`, we have successfully broadcast your transaction to the current and next 4 leaders. If it doesn't land:
1.  **Blockhash Expired:** Your transaction might have been built with an old blockhash. Use our **gRPC Service** or a fast RPC to get the latest blockhash.
2.  **Slippage/State:** The on-chain state might have changed (e.g., the pool price moved), causing the transaction to fail execution on the validator.
3.  **Tip Too Low:** During extreme congestion, 0.001 SOL might not be enough to incentivize the leader. Try increasing your tip to 0.002–0.005 SOL.

### Performance & Limits

**Q: What is the rate limit?**
A: Default standard plans include **100 requests/second**.
*   **Bursting:** We allow short bursts up to 150/s.
*   **Exceeding:** You will receive `429 Too Many Requests`.
*   **Upgrades:** Enterprise plans with active co-location have effectively unlimited throughput (10,000+ tx/s).

**Q: Is QUIC really faster than HTTPS?**
A: **Yes, significantly.**
*   **HTTPS:** Requires a TCP handshake + TLS handshake for every new connection (~3-4 round trips).
*   **QUIC:** Uses a persistent UDP connection with 0-RTT resumption. Once connected, sending a transaction is just one packet.
*   **Recommendation:** Use HTTPS for testing/scripts, but **always use QUIC** for live trading bots.

### Security

**Q: What if my API Key is compromised?**
A: Contact support via Discord immediately. We can rotate your key instantly without requiring a code deploy on your end if you load keys from env vars.
*   **Best Practice:** Never commit keys to GitHub. Use `.env` files.

**Q: Do you front-run my transactions?**
A: **Absolutely not.** The core value proposition of AllenHark Relay is **MEV protection**. We route your transaction solely to the leader via private TPU ports. It is never broadcast to the public gossip network until it lands in a block.

---

## Performance Tuning
*   **Co-Location**: For ultimate performance, host your bots in our Frankfurt datacenter (TeraSwitch).
*   **Keep-Alive**: Reuse QUIC connections. Set keep-alive pings to 3s to prevent timeouts.
*   **Pre-flight**: Skip pre-flight checks in your client to save time; validation happens server-side.