Skip to content

Commit 27c35f9

Browse files
nidhi-singh02nidhi-singh02
authored
Merge pull request #3022 from pyth-network/add-express-relay-ref-and-how
chore(express-relay): reference section and how it works
2 parents 07835ec + 382f70d commit 27c35f9

File tree

8 files changed

+861
-0
lines changed

8 files changed

+861
-0
lines changed

‎apps/developer-hub/content/docs/express-relay/contract-addresses.mdx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: "SVM Contract Addresses"
3+
description: >-
4+
Contract addresses and network details for Express Relay deployment on Solana Virtual Machine environments.
5+
---
6+
7+
# SVM Contract Addresses
8+
9+
Express Relay is currently deployed on the following SVM environments:
10+
11+
## Production (Solana Mainnet-Beta)
12+
13+
**Auction Server endpoint:** https://per-mainnet.dourolabs.app/
14+
15+
| Name | Address/Value |
16+
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
17+
| Express Relay Program | [PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou](https://solscan.io/account/PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou) |
18+
| Limo Limit Order Program | [LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF](https://solscan.io/account/LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF) |
19+
| Chain Id | solana |
20+
| Public RPC | https://api.mainnet-beta.solana.com |
21+
| Limo Global Order Config | [prod7Mog8r56sn5dPwze8nVdf94veEawdxNNqd5v7A1](https://solscan.io/account/prod7Mog8r56sn5dPwze8nVdf94veEawdxNNqd5v7A1) |
22+
| Frontend | https://swap.kamino.finance |
23+
24+
## Testing (Solana Mainnet-Beta)
25+
26+
> **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.
27+
28+
**Auction Server endpoint:** https://per-staging.dourolabs.app/
29+
30+
| Name | Address/Value |
31+
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
32+
| Express Relay Program (Swaps) | [stag1NN9voD7436oFvKmy1kvRZYLLW8drKocSCt2W79](https://solscan.io/account/stag1NN9voD7436oFvKmy1kvRZYLLW8drKocSCt2W79) |
33+
| Express Relay Program (Limit Orders) | [PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou](https://solscan.io/account/PytERJFhAKuNNuaiXkApLfWzwNwSNDACpigT3LwQfou) |
34+
| Limo Limit Order Program | [LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF](https://solscan.io/account/LiMoM9rMhrdYrfzUCxQppvxCSG1FcrUK9G8uLq4A1GF) |
35+
| Chain Id | development-solana |
36+
| Public RPC | https://api.mainnet-beta.solana.com |
37+
| Limo Global Order Config | [TeStcUQMmECYEtdeXo9cXpktQWaGe4bhJ7zxAUMzB2X](https://solscan.io/account/TeStcUQMmECYEtdeXo9cXpktQWaGe4bhJ7zxAUMzB2X) |
38+
| Testing Frontend | https://limo.kamino-webapp.pages.dev/swap |
39+
40+
### Common Assets on development-solana
41+
42+
| Asset | Address |
43+
| ----- | ----------------------------------------------------------------------------------------------------------------------- |
44+
| WSOL | [So11111111111111111111111111111111111111112](https://solscan.io/account/So11111111111111111111111111111111111111112) |
45+
| USDC | [EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v](https://solscan.io/account/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) |

‎apps/developer-hub/content/docs/express-relay/errors.mdx‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
title: "Error Codes"
3+
description: >-
4+
Reference guide for Express Relay error codes and troubleshooting common issues.
5+
---
6+
7+
# Error Codes
8+
9+
This page provides a reference for common error codes you may encounter when integrating with Express Relay, along with explanations and suggested solutions.
10+
11+
## HTTP API Errors
12+
13+
### 400 Bad Request
14+
15+
**Invalid chain_id**
16+
17+
- **Error:** Chain ID is not supported
18+
- **Solution:** Ensure you're using a supported chain ID (e.g., "solana", "development-solana")
19+
20+
**Invalid transaction format**
21+
22+
- **Error:** Transaction data is not properly encoded
23+
- **Solution:** Ensure transaction is base64 encoded and properly formatted
24+
25+
**Missing required fields**
26+
27+
- **Error:** Required fields are missing from the request
28+
- **Solution:** Check that all required parameters are included in your request
29+
30+
### 401 Unauthorized
31+
32+
**Invalid authentication**
33+
34+
- **Error:** Authentication credentials are invalid or missing
35+
- **Solution:** Verify your API credentials and authentication headers
36+
37+
### 404 Not Found
38+
39+
**Opportunity not found**
40+
41+
- **Error:** The requested opportunity does not exist
42+
- **Solution:** Check that the opportunity ID is correct and the opportunity hasn't expired
43+
44+
### 429 Too Many Requests
45+
46+
**Rate limit exceeded**
47+
48+
- **Error:** Too many requests sent in a short time period
49+
- **Solution:** Implement exponential backoff and respect rate limits
50+
51+
### 500 Internal Server Error
52+
53+
**Server error**
54+
55+
- **Error:** Internal server error occurred
56+
- **Solution:** Retry the request after a brief delay. If the issue persists, contact support
57+
58+
## WebSocket Errors
59+
60+
### Connection Errors
61+
62+
**Connection failed**
63+
64+
- **Error:** Unable to establish WebSocket connection
65+
- **Solution:** Check network connectivity and WebSocket endpoint URL
66+
67+
**Authentication failed**
68+
69+
- **Error:** WebSocket authentication failed
70+
- **Solution:** Verify authentication credentials for WebSocket connection
71+
72+
### Subscription Errors
73+
74+
**Invalid subscription**
75+
76+
- **Error:** Subscription parameters are invalid
77+
- **Solution:** Check that chain_ids array contains valid chain identifiers
78+
79+
**Subscription limit exceeded**
80+
81+
- **Error:** Too many active subscriptions
82+
- **Solution:** Unsubscribe from unused chains before subscribing to new ones
83+
84+
## Transaction Errors
85+
86+
### Bid Submission Errors
87+
88+
**Insufficient balance**
89+
90+
- **Error:** Insufficient funds to cover bid amount
91+
- **Solution:** Ensure wallet has sufficient balance for the bid amount plus transaction fees
92+
93+
**Invalid bid amount**
94+
95+
- **Error:** Bid amount is below minimum or above maximum
96+
- **Solution:** Check bid amount constraints for the specific opportunity
97+
98+
**Permission denied**
99+
100+
- **Error:** Not authorized to submit bid for this opportunity
101+
- **Solution:** Verify permission key and ensure proper authorization
102+
103+
### On-Chain Execution Errors
104+
105+
**Transaction failed**
106+
107+
- **Error:** Transaction execution failed on-chain
108+
- **Solution:** Check transaction logs for specific failure reasons
109+
110+
**Transaction expired**
111+
112+
- **Error:** Transaction expired before execution
113+
- **Solution:** Submit bids with sufficient time before deadline
114+
115+
**Insufficient gas/compute**
116+
117+
- **Error:** Transaction ran out of gas or compute units
118+
- **Solution:** Increase gas limit or compute unit allocation
119+
120+
## SDK-Specific Errors
121+
122+
### JavaScript SDK Errors
123+
124+
**Network timeout**
125+
126+
- **Error:** Request timed out
127+
- **Solution:** Increase timeout configuration or check network connectivity
128+
129+
**Invalid configuration**
130+
131+
- **Error:** SDK configuration is invalid
132+
- **Solution:** Verify baseUrl and other configuration parameters
133+
134+
### Python SDK Errors
135+
136+
**Connection error**
137+
138+
- **Error:** Failed to connect to Express Relay server
139+
- **Solution:** Check network connectivity and server endpoint
140+
141+
**Serialization error**
142+
143+
- **Error:** Failed to serialize/deserialize data
144+
- **Solution:** Ensure data types match expected format
145+
146+
## Troubleshooting Tips
147+
148+
### General Guidelines
149+
150+
1. **Check network connectivity** - Ensure your application can reach Express Relay endpoints
151+
2. **Verify parameters** - Double-check all request parameters for correct format and values
152+
3. **Monitor rate limits** - Implement proper rate limiting to avoid 429 errors
153+
4. **Handle timeouts** - Implement retry logic with exponential backoff
154+
5. **Check logs** - Review both client and server logs for detailed error information
155+
156+
### Getting Help
157+
158+
If you encounter persistent issues:
159+
160+
1. Check the [API documentation](https://per-mainnet.dourolabs.app/docs) for detailed endpoint specifications
161+
2. Review example implementations in the SDK repositories
162+
3. Join the community Discord for support and discussion
163+
4. Contact technical support with detailed error information and reproduction steps
164+
165+
### Common Patterns
166+
167+
**Retry Logic Example**
168+
169+
```typescript
170+
const maxRetries = 3;
171+
let retryCount = 0;
172+
173+
while (retryCount < maxRetries) {
174+
try {
175+
const result = await client.submitBid(bid);
176+
return result;
177+
} catch (error) {
178+
retryCount++;
179+
if (retryCount === maxRetries) {
180+
throw error;
181+
}
182+
await new Promise((resolve) => setTimeout(resolve, 1000 * retryCount));
183+
}
184+
}
185+
```
186+
187+
**Error Handling Example**
188+
189+
```typescript
190+
try {
191+
const opportunities = await client.getOpportunities();
192+
} catch (error) {
193+
if (error.status === 429) {
194+
// Rate limited - wait and retry
195+
await new Promise((resolve) => setTimeout(resolve, 5000));
196+
} else if (error.status === 500) {
197+
// Server error - log and alert
198+
console.error("Server error:", error);
199+
} else {
200+
// Other errors - handle appropriately
201+
console.error("Request failed:", error);
202+
}
203+
}
204+
```

‎apps/developer-hub/content/docs/express-relay/how-express-relay-works/auction.mdx‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: "Auction Mechanism"
3+
description: >-
4+
Learn how Express Relay's off-chain auction determines winning bids and maximizes revenue sharing with integrated protocols.
5+
---
6+
7+
# Auction
8+
9+
The auction in Express Relay is held off-chain at the auction server.
10+
Bids arrive at the auction server and compete against other bids, vying for the same [permission key](./permissioning).
11+
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.
12+
13+
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.
14+
15+
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**.
16+
17+
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.
18+
19+
The **ExpressRelay** contract extracts the payment of the specified bid amount only if the searcher's bid is successfully executed on-chain.
20+
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.
21+
22+
## Revenue Sharing
23+
24+
The revenue from the auction is shared amongst relevant stakeholders in the Express Relay system. These stakeholders include:
25+
26+
- **The protocol** that generates the relevant opportunity
27+
- **The relayer**, which handles running the off-chain components of the system
28+
29+
> **ℹ️ Revenue Distribution**: The Express Relay contract enforces the exact revenue splits and is subject to change based on governance decisions.

0 commit comments

Comments
 (0)