internet-court/internet-court-skill / vendored/sendaifun/debridge
debridge
VerifiedComplete deBridge Protocol SDK for building cross-chain bridges, message passing, and token transfers on Solana. Use when building cross-chain applications, bridging assets between Solana and EVM chains, or implementing trustless external calls.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 11.1 KB |
| SKILL.md | skill md | 19.2 KB |
| docs/troubleshooting.md | markdown | 9.5 KB |
| examples/basic-transfer/README.md | markdown | 12.3 KB |
| examples/external-calls/README.md | markdown | 13.5 KB |
| examples/fee-configurations/README.md | markdown | 13.5 KB |
| examples/message-passing/README.md | markdown | 14.5 KB |
| resources/chain-ids.md | markdown | 5.1 KB |
| resources/error-codes.md | markdown | 9.2 KB |
| resources/program-ids.md | markdown | 7.5 KB |
| resources/sdk-api-reference.md | markdown | 10.8 KB |
docs/troubleshooting.md
View on GitHub# deBridge Troubleshooting Guide
Common issues and solutions when integrating deBridge on Solana.
## Common Errors
### 1. TargetChainNotSupported
**Error:** `TargetChainNotSupported`
**Cause:** The destination chain is not enabled in deBridge.
**Solution:**
```rust
// Check chain support before sending
let is_supported = debridge_sending::is_chain_supported(
&target_chain_id,
ctx.remaining_accounts,
)?;
if !is_supported {
return Err(error!(ErrorCode::UnsupportedChain));
}
```
**TypeScript:**
```typescript
// Verify chain ID format
const targetChainId = evmChainIdToBytes(1n); // Ethereum
// Check support
const supported = await program.methods
.isChainSupported(targetChainId)
.view();
```
### 2. WrongAccountDiscriminator
**Error:** `WrongAccountDiscriminator`
**Cause:** Account passed to SDK is not the expected type.
**Solution:**
- Verify account derivation using correct PDAs
- Check program IDs are correct (DEBRIDGE_ID, SETTINGS_ID)
- Ensure accounts are in correct order
```rust
use debridge_solana_sdk::keys::*;
// Correct PDA derivation
let (bridge, _) = Pubkey::find_bridge_address(&token_mint);
let (chain_support, _) = Pubkey::find_chain_support_info_address(&chain_id);
```
### 3. AssetFeeNotSupported
**Error:** `AssetFeeNotSupported`
**Cause:** Trying to use asset fee when not available for the chain.
**Solution:**
```rust
// Check availability before using asset fee
if debridge_sending::is_asset_fee_available(&chain_id, accounts)? {
// Use asset fee
is_use_asset_fee: true
} else {
// Fall back to native fee
is_use_asset_fee: false
}
```
### 4. AmountOverflowedWhileAddingFee
**Error:** `AmountOverflowedWhileAddingFee`
**Cause:** Amount + fees exceeds u64::MAX.
**Solution:**
```rust
// Check for potential overflow
let max_safe_amount = u64::MAX / 2; // Conservative limit
require!(
amount < max_safe_amount,
ErrorCode::AmountTooLarge
);
let total = debridge_sending::add_all_fees(amount, &chain_id, accounts)?;
```
### 5. WrongClaimParentSubmissionAuth
**Error:** `WrongClaimParentSubmissionAuth`
**Cause:** Claim validation failed - submission authority mismatch.
**Solution:**
```rust
// Ensure correct validation setup
let claim_ix = ValidatedExecuteExtCallIx::try_from_current_ix()?;
// Validate against expected values
claim_ix.validate_submission_auth(&expected_authority)?;
```
### 6. ExternalStorageWrongState
**Error:** `ExternalStorageWrongState`
**Cause:** External call storage account in unexpected state.
**Solution:**
- Initialize storage before use
- Don't reuse already-used storage accounts
- Check if storage already exists before init
```rust
// Initialize external call storage first
invoke_init_external_call(
InitExternalCallIx {
external_call_len: data.len() as u32,
chain_id: target_chain_id,
external_call_shortcut: shortcut,
external_call: data,
},
accounts,
)?;
```
## Account Issues
### Wrong Account Order
**Problem:** Transaction fails silently or with generic error.
**Solution:** Follow exact account order:
```rust
// Required account order for invoke_debridge_send
let remaining_accounts = vec![
AccountMeta::new(bridge, false), // 0
AccountMeta::new_readonly(token_mint, false), // 1
AccountMeta::new(staking_wallet, false), // 2
AccountMeta::new_readonly(mint_auth, false), // 3
AccountMeta::new_readonly(chain_info, false), // 4
AccountMeta::new_readonly(settings, false), // 5
AccountMeta::new_readonly(token_prog, false), // 6
AccountMeta::new_readonly(state, false), // 7
AccountMeta::new_readonly(debridge, false), // 8
AccountMeta::new(nonce_storage, false), // 9
// ... more accounts
];
```
### Missing Accounts
**Problem:** `AccountNotEnoughKeys` or similar.
**Solution:**
1. Count required accounts in SDK documentation
2. Verify all PDAs are derived correctly
3. Include all token accounts
### Account Not Initialized
**Problem:** Account has no data or wrong owner.
**Solution:**
```typescript
// Check account exists
const accountInfo = await connection.getAccountInfo(bridgePda);
if (!accountInfo) {
throw new Error('Bridge account not initialized for this token');
}
// Verify owner
if (!accountInfo.owner.equals(DEBRIDGE_PROGRAM_ID)) {
throw new Error('Wrong account owner');
}
```
## Transaction Issues
### Transaction Too Large
**Problem:** Transaction exceeds size limit.
**Solution:**
1. Use `init_external_call` for large payloads
2. Split into multiple transactions
3. Use versioned transactions with lookup tables
```typescript
// For large external calls
const { data, shortcut } = buildExternalCallData(...);
if (data.length > 450) {
// Initialize storage first
await program.methods
.initExternalCallBuffer(targetChainId, Buffer.from(data))
.rpc();
}
// Then send
await program.methods
.sendWithExternalCall(...)
.rpc();
```
### Compute Budget Exceeded
**Problem:** Transaction runs out of compute units.
**Solution:**
```typescript
import { ComputeBudgetProgram } from '@solana/web3.js';
const tx = new Transaction()
.add(
ComputeBudgetProgram.setComputeUnitLimit({
units: 400_000, // Increase limit
})
)
.add(
// Your deBridge instruction
);
```
### Blockhash Expired
**Problem:** Transaction confirmation times out.
**Solution:**
```typescript
// Use confirmed commitment
const { blockhash, lastValidBlockHeight } =
await connection.getLatestBlockhash('confirmed');
// Retry with exponential backoff
async function sendWithRetry(tx: Transaction, retries = 3) {
for (let i = 0; i < retries; i++) {
try {
return await connection.sendTransaction(tx, [signer]);
} catch (e) {
if (i === retries - 1) throw e;
await new Promise(r => setTimeout(r, 1000 * (i + 1)));
}
}
}
```
## Fee Issues
### Insufficient SOL for Native Fee
**Problem:** User doesn't have enough SOL for protocol fees.
**Solution:**
```typescript
// Check balance before sending
const balance = await connection.getBalance(sender);
const nativeFee = await getNativeFee(chainId);
if (balance < nativeFee + 5000) { // 5000 for tx fee
throw new Error('Insufficient SOL balance');
}
// Or use asset fee
if (await isAssetFeeAvailable(chainId)) {
sendWithAssetFee(...);
}
```
### Fee Changed Between Quote and Send
**Problem:** Fees changed after user approved transaction.
**Solution:**
```typescript
// Get fresh fees right before sending
const fees = await getFeeBreakdown(chainId, amount);
// Add slippage tolerance
const maxAmount = amount + (amount * 1n / 100n); // 1% tolerance
if (fees.amountWithAllFees > maxAmount) {
throw new Error('Fee increased significantly');
}
```
## Receiver Address Issues
### Invalid EVM Address Length
**Problem:** Receiver address wrong length.
**Solution:**
```typescript
function validateEvmAddress(address: string): Uint8Array {
// Remove 0x prefix
const hex = address.replace('0x', '');
// Check length
if (hex.length !== 40) {
throw new Error('EVM address must be 20 bytes');
}
// Check valid hex
if (!/^[0-9a-fA-F]+$/.test(hex)) {
throw new Error('Invalid hex characters');
}
// Convert to bytes
const bytes = new Uint8Array(20);
for (let i = 0; i < 20; i++) {
bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
}
return bytes;
}
```
### Checksum Address Issues
**Problem:** Address has wrong checksum.
**Solution:**
```typescript
import { getAddress } from 'ethers';
function normalizeEvmAddress(address: string): string {
try {
// This validates checksum and normalizes
return getAddress(address);
} catch {
throw new Error('Invalid EVM address checksum');
}
}
```
## Testing Issues
### Mainnet-Only Infrastructure
**Problem:** deBridge not available on devnet.
**Solution:**
```typescript
// Use mainnet fork for testing
const connection = new Connection(
'https://api.mainnet-beta.solana.com',
{ commitment: 'confirmed' }
);
// Or mock the SDK responses for unit tests
jest.mock('debridge-solana-sdk', () => ({
// Mock implementations
}));
```
### Airdrop Limits
**Problem:** Can't get enough SOL for testing on mainnet.
**Solution:**
1. Use small amounts for testing
2. Create dedicated test wallet with mainnet SOL
3. Use mainnet fork that allows airdrops
## Debug Logging
Enable detailed logging:
```rust
// In your program
msg!("deBridge: Sending {} to chain {:?}", amount, target_chain_id);
msg!("deBridge: Using asset fee: {}", is_use_asset_fee);
msg!("deBridge: Accounts count: {}", ctx.remaining_accounts.len());
// Log each account
for (i, account) in ctx.remaining_accounts.iter().enumerate() {
msg!("Account {}: {} (signer: {}, writable: {})",
i,
account.key,
account.is_signer,
account.is_writable
);
}
```
```typescript
// TypeScript logging
console.log('deBridge Transfer:');
console.log(' Target Chain:', targetChainId);
console.log(' Receiver:', receiver);
console.log(' Amount:', amount);
console.log(' Accounts:', remainingAccounts.map(a => ({
pubkey: a.pubkey.toBase58(),
isSigner: a.isSigner,
isWritable: a.isWritable,
})));
```
## Getting Help
1. **deBridge Docs**: https://docs.debridge.com
2. **SDK GitHub**: https://github.com/debridge-finance/debridge-solana-sdk
3. **Discord**: https://discord.gg/debridge
4. **SDK Issues**: Open issue on GitHub repo
When reporting issues, include:
- Transaction signature (if available)
- Error message
- Chain IDs involved
- Token mint address
- Amount being transferred
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |