Skip to content

chore(developer-hub): enhancements in the express relay #3034

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 11, 2025
Merged

chore(developer-hub): enhancements in the express relay #3034

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7e3bf8b
enhancements in the express relay
nidhi-singh02 Sep 9, 2025
da21bea
formating fix and use copy address directly
nidhi-singh02 Sep 9, 2025
c7f95ef
add alt text, links and warning format
nidhi-singh02 Sep 11, 2025
27e645a
test formating
nidhi-singh02 Sep 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 49 additions & 40 deletions apps/developer-hub/content/docs/express-relay/contract-addresses.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,54 @@
---
title: "SVM Contract Addresses"
description: >-
Contract addresses and network details for Express Relay deployment on Solana Virtual Machine environments.
Express Relay is currently deployed on the following SVM environments:
---

# SVM Contract Addresses

Express Relay is currently deployed on the following SVM environments:

## Production (Solana Mainnet-Beta)

**Auction Server endpoint:** https://per-mainnet.dourolabs.app/

| Name | Address/Value |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Express Relay Program | [PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou](https://solscan.io/account/PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou) |
| Limo Limit Order Program | [LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF](https://solscan.io/account/LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF) |
| Chain Id | solana |
| Public RPC | https://api.mainnet-beta.solana.com |
| Limo Global Order Config | [prod7Mog8r56sn5dPwze8nVdf94veEawdxNNqd5v7A1](https://solscan.io/account/prod7Mog8r56sn5dPwze8nVdf94veEawdxNNqd5v7A1) |
| Frontend | https://swap.kamino.finance |

## Testing (Solana Mainnet-Beta)

> **Warning**: To simulate real performance conditions and activity, the staging/testing environment for Solana is on the mainnet-beta network. This environment is not for production use and should only be used for testing.
**Auction Server endpoint:** https://per-staging.dourolabs.app/

| Name | Address/Value |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Express Relay Program (Swaps) | [stag1NN9voD7436oFvKmy1kvRZYLLW8drKocSCt2W79](https://solscan.io/account/stag1NN9voD7436oFvKmy1kvRZYLLW8drKocSCt2W79) |
| Express Relay Program (Limit Orders) | [PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou](https://solscan.io/account/PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou) |
| Limo Limit Order Program | [LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF](https://solscan.io/account/LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF) |
| Chain Id | development-solana |
| Public RPC | https://api.mainnet-beta.solana.com |
| Limo Global Order Config | [TeStcUQMmECYEtdeXo9cXpktQWaGe4bhJ7zxAUMzB2X](https://solscan.io/account/TeStcUQMmECYEtdeXo9cXpktQWaGe4bhJ7zxAUMzB2X) |
| Testing Frontend | https://limo.kamino-webapp.pages.dev/swap |

### Common Assets on development-solana

| Asset | Address |
| ----- | ----------------------------------------------------------------------------------------------------------------------- |
| WSOL | [So11111111111111111111111111111111111111112](https://solscan.io/account/So11111111111111111111111111111111111111112) |
| USDC | [EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v](https://solscan.io/account/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) |
import CopyAddress from "../../../src/components/CopyAddress";

<Tabs items={['Production', 'Testing']}>
<Tab value="production">

**Auction Server endpoint:** <CopyAddress address="https://per-mainnet.dourolabs.app/" />

**Network Details (Solana Mainnet-Beta):**
| Name | Address/Value |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Express Relay Program | <CopyAddress address="PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou" url="https://solscan.io/account/PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou" /> |
| Limo Limit Order Program | <CopyAddress address="LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF" url="https://solscan.io/account/LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF" /> |
| Chain Id | <CopyAddress address="solana" /> |
| Public RPC | <CopyAddress address="https://api.mainnet-beta.solana.com" /> |
| Limo Global Order Config | <CopyAddress address="prod7Mog8r56sn5dPwze8nVdf94veEawdxNNqd5v7A1" url="https://solscan.io/account/prod7Mog8r56sn5dPwze8nVdf94veEawdxNNqd5v7A1" /> |
| Frontend | <CopyAddress address="https://swap.kamino.finance" url="https://swap.kamino.finance" /> |

</Tab>
<Tab value="testing">

<Callout variant="warning">
To simulate real performance conditions and activity, the staging/testing
environment for Solana is on the mainnet-beta network. This environment is not
for production use and should only be used for testing.
</Callout>
Comment on lines +27 to +31
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using a Callout which seems much better.


**Auction Server endpoint:** <CopyAddress address="https://per-staging.dourolabs.app/" />

**Network Details (Solana Mainnet-Beta):**
| Name | Address/Value |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Express Relay Program (Swaps) | <CopyAddress address="stag1NN9voD7436oFvKmy1kvRZYLLW8drKocSCt2W79" url="https://solscan.io/account/stag1NN9voD7436oFvKmy1kvRZYLLW8drKocSCt2W79" /> |
| Express Relay Program (Limit Orders) | <CopyAddress address="PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou" url="https://solscan.io/account/PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou" /> |
| Limo Limit Order Program | <CopyAddress address="LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF" url="https://solscan.io/account/LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF" /> |
| Chain Id | <CopyAddress address="development-solana" /> |
| Public RPC | <CopyAddress address="https://api.mainnet-beta.solana.com" /> |
| Limo Global Order Config | <CopyAddress address="TeStcUQMmECYEtdeXo9cXpktQWaGe4bhJ7zxAUMzB2X" url="https://solscan.io/account/TeStcUQMmECYEtdeXo9cXpktQWaGe4bhJ7zxAUMzB2X" /> |
| Testing Frontend | <CopyAddress address="https://limo.kamino-webapp.pages.dev/swap" url="https://limo.kamino-webapp.pages.dev/swap" /> |

\*\* This list contains the addresses of the commonly used assets present in opportunities on development-solana:

| Asset | Address |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| WSOL | <CopyAddress address="So11111111111111111111111111111111111111112" url="https://solscan.io/account/So11111111111111111111111111111111111111112" /> |
| USDC | <CopyAddress address="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" url="https://solscan.io/account/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" /> |

</Tab>
</Tabs>
225 changes: 26 additions & 199 deletions apps/developer-hub/content/docs/express-relay/errors.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,204 +1,31 @@
---
title: "Error Codes"
title: "SVM Error Codes"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe this should be Express Relay Error Codes instead? I feel like SVM Error Codes is too generic but feel free to ignore if it doesn't make sense

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As we are inside Express Relay, SVM Error Codes seems okay to me.

description: >-
Reference guide for Express Relay error codes and troubleshooting common issues.
---

# Error Codes

This page provides a reference for common error codes you may encounter when integrating with Express Relay, along with explanations and suggested solutions.

## HTTP API Errors

### 400 Bad Request

**Invalid chain_id**

- **Error:** Chain ID is not supported
- **Solution:** Ensure you're using a supported chain ID (e.g., "solana", "development-solana")

**Invalid transaction format**

- **Error:** Transaction data is not properly encoded
- **Solution:** Ensure transaction is base64 encoded and properly formatted

**Missing required fields**

- **Error:** Required fields are missing from the request
- **Solution:** Check that all required parameters are included in your request

### 401 Unauthorized

**Invalid authentication**

- **Error:** Authentication credentials are invalid or missing
- **Solution:** Verify your API credentials and authentication headers

### 404 Not Found

**Opportunity not found**

- **Error:** The requested opportunity does not exist
- **Solution:** Check that the opportunity ID is correct and the opportunity hasn't expired

### 429 Too Many Requests

**Rate limit exceeded**

- **Error:** Too many requests sent in a short time period
- **Solution:** Implement exponential backoff and respect rate limits

### 500 Internal Server Error

**Server error**

- **Error:** Internal server error occurred
- **Solution:** Retry the request after a brief delay. If the issue persists, contact support

## WebSocket Errors

### Connection Errors

**Connection failed**

- **Error:** Unable to establish WebSocket connection
- **Solution:** Check network connectivity and WebSocket endpoint URL

**Authentication failed**

- **Error:** WebSocket authentication failed
- **Solution:** Verify authentication credentials for WebSocket connection

### Subscription Errors

**Invalid subscription**

- **Error:** Subscription parameters are invalid
- **Solution:** Check that chain_ids array contains valid chain identifiers

**Subscription limit exceeded**

- **Error:** Too many active subscriptions
- **Solution:** Unsubscribe from unused chains before subscribing to new ones

## Transaction Errors

### Bid Submission Errors

**Insufficient balance**

- **Error:** Insufficient funds to cover bid amount
- **Solution:** Ensure wallet has sufficient balance for the bid amount plus transaction fees

**Invalid bid amount**

- **Error:** Bid amount is below minimum or above maximum
- **Solution:** Check bid amount constraints for the specific opportunity

**Permission denied**

- **Error:** Not authorized to submit bid for this opportunity
- **Solution:** Verify permission key and ensure proper authorization

### On-Chain Execution Errors

**Transaction failed**

- **Error:** Transaction execution failed on-chain
- **Solution:** Check transaction logs for specific failure reasons

**Transaction expired**

- **Error:** Transaction expired before execution
- **Solution:** Submit bids with sufficient time before deadline

**Insufficient gas/compute**

- **Error:** Transaction ran out of gas or compute units
- **Solution:** Increase gas limit or compute unit allocation

## SDK-Specific Errors

### JavaScript SDK Errors

**Network timeout**

- **Error:** Request timed out
- **Solution:** Increase timeout configuration or check network connectivity

**Invalid configuration**

- **Error:** SDK configuration is invalid
- **Solution:** Verify baseUrl and other configuration parameters

### Python SDK Errors

**Connection error**

- **Error:** Failed to connect to Express Relay server
- **Solution:** Check network connectivity and server endpoint

**Serialization error**

- **Error:** Failed to serialize/deserialize data
- **Solution:** Ensure data types match expected format

## Troubleshooting Tips

### General Guidelines

1. **Check network connectivity** - Ensure your application can reach Express Relay endpoints
2. **Verify parameters** - Double-check all request parameters for correct format and values
3. **Monitor rate limits** - Implement proper rate limiting to avoid 429 errors
4. **Handle timeouts** - Implement retry logic with exponential backoff
5. **Check logs** - Review both client and server logs for detailed error information

### Getting Help

If you encounter persistent issues:

1. Check the [API documentation](https://per-mainnet.dourolabs.app/docs) for detailed endpoint specifications
2. Review example implementations in the SDK repositories
3. Join the community Discord for support and discussion
4. Contact technical support with detailed error information and reproduction steps

### Common Patterns

**Retry Logic Example**

```typescript
const maxRetries = 3;
let retryCount = 0;

while (retryCount < maxRetries) {
try {
const result = await client.submitBid(bid);
return result;
} catch (error) {
retryCount++;
if (retryCount === maxRetries) {
throw error;
}
await new Promise((resolve) => setTimeout(resolve, 1000 * retryCount));
}
}
```

**Error Handling Example**

```typescript
try {
const opportunities = await client.getOpportunities();
} catch (error) {
if (error.status === 429) {
// Rate limited - wait and retry
await new Promise((resolve) => setTimeout(resolve, 5000));
} else if (error.status === 500) {
// Server error - log and alert
console.error("Server error:", error);
} else {
// Other errors - handle appropriately
console.error("Request failed:", error);
}
}
```
The following table lists the error codes and their explanations for the ExpressRelay programs. They can be used to identify the cause of a failed transaction or bid.

## ExpressRelay

| Error Code | Name | Description |
| ---------- | ---------------------------------- | ---------------------------------------------------------- |
| 6000 | `InvalidPermissionPda` | The permission PDA is invalid |
| 6001 | `InvalidPermissionKeypair` | The permission keypair is invalid |
| 6002 | `InvalidRouter` | The router is invalid |
| 6003 | `DeadlineExceeded` | The bid deadline has been exceeded |
| 6004 | `InsufficientFee` | The fee is insufficient |
| 6005 | `InvalidChainId` | The chain ID is invalid |
| 6006 | `InvalidFeeReceiver` | The fee receiver is invalid |
| 6007 | `InvalidFeePayer` | The fee payer is invalid |
| 6008 | `InvalidRelayerSigner` | The relayer signer is invalid |
| 6009 | `RouterExecutionFailed` | Router execution failed |
| 6010 | `BidAmountTooLow` | The bid amount is too low |
| 6011 | `InvalidBidAmount` | The bid amount is invalid |
| 6012 | `PermissionAccountNotWritable` | The permission account is not writable |
| 6013 | `InvalidDestination` | The destination is invalid |
| 6014 | `InvalidMetadata` | The metadata is invalid |
| 6015 | `InvalidConfigPda` | The config PDA is invalid |
| 6016 | `InvalidAdmin` | The admin is invalid |
| 6017 | `FeeSplitOutOfRange` | The fee split is out of range |
| 6018 | `MaxBidAmountLessThanMinBidAmount` | The maximum bid amount is less than the minimum bid amount |
20 changes: 8 additions & 12 deletions apps/developer-hub/content/docs/express-relay/how-express-relay-works/auction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,25 @@
---
title: "Auction Mechanism"
title: "Auction"
description: >-
Learn how Express Relay's off-chain auction determines winning bids and maximizes revenue sharing with integrated protocols.
---

# Auction

The auction in Express Relay is held off-chain at the auction server.
Bids arrive at the auction server and compete against other bids, vying for the same [permission key](./permissioning).
Bids arrive at the auction server and compete against other bids, vying for the same [permission key](permissioning).
A relayer selected by governance serves as the auctioneer and determines the auction in line with the criterion of maximizing the revenue shared back to the protocol that generated this opportunity. That means the auctioneer is expected to forward on-chain the subset of bids that maximizes the revenue back to the protocol.

Thus, the Express Relay auction is analogous to a sealed-bid auction, i.e., participants in the auction will not have the contents of their bid disclosed publicly unless they win the auction and are forwarded on-chain.

The forwarded subset of transactions is submitted on-chain and first processed by the [`ExpressRelay`](https://github.com/pyth-network/per/blob/fccac65b00cff1cfe5c278b333a582fe66bda0f8/contracts/evm/src/express-relay/ExpressRelay.sol) contract before individual searchers' submissions are routed to their corresponding **targetContracts**.
The forwarded subset of transactions is submitted on-chain and first processed by the [`ExpressRelay`](https://github.com/pyth-network/per/blob/fccac65b00cff1cfe5c278b333a582fe66bda0f8/contracts/evm/src/express-relay/ExpressRelay.sol) contract before individual searchers' submissions are routed to their corresponding `targetContract`s.

Generally, the auction server expects bids to execute successfully on-chain. Fallback bids are also forwarded in case of execution failures for the predicted winners.
Generally, the auction server expects bids to execute successfully on-chain. Falback bids are also forwarded in case of execution failures for the predicted winners.

The **ExpressRelay** contract extracts the payment of the specified bid amount only if the searcher's bid is successfully executed on-chain.
The `ExpressRelay` contract extracts the payment of the specified bid amount only if the searcher's bid is successfully executed on-chain.
Hence, the Express Relay auction can be seen as a generalization of a [first-price sealed-bid auction](https://en.wikipedia.org/wiki/First-price_sealed-bid_auction), in that multiple bids can win and pay their first price.

## Revenue Sharing

The revenue from the auction is shared amongst relevant stakeholders in the Express Relay system. These stakeholders include:

- **The protocol** that generates the relevant opportunity
- **The relayer**, which handles running the off-chain components of the system
- the protocol that generates the relevant opportunity
- the relayer, which handles running the off-chain components of the system

> **ℹ️ Revenue Distribution**: The Express Relay contract enforces the exact revenue splits and is subject to change based on governance decisions.
The Express Relay contract enforces the exact revenue splits and is subject to change based on governance decisions.
Loading
Loading