Add Oracle Aggregator and CCIP Integration
- Introduced Aggregator.sol for Chainlink-compatible oracle functionality, including round-based updates and access control. - Added OracleWithCCIP.sol to extend Aggregator with CCIP cross-chain messaging capabilities. - Created .gitmodules to include OpenZeppelin contracts as a submodule. - Developed a comprehensive deployment guide in NEXT_STEPS_COMPLETE_GUIDE.md for Phase 2 and smart contract deployment. - Implemented Vite configuration for the orchestration portal, supporting both Vue and React frameworks. - Added server-side logic for the Multi-Cloud Orchestration Portal, including API endpoints for environment management and monitoring. - Created scripts for resource import and usage validation across non-US regions. - Added tests for CCIP error handling and integration to ensure robust functionality. - Included various new files and directories for the orchestration portal and deployment scripts.
This commit is contained in:
defiQUG
221
docs/api/API.md
Normal file
221
docs/api/API.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# API Documentation
|
||||
|
||||
## JSON-RPC API
|
||||
|
||||
The DeFi Oracle Meta Mainnet provides a public JSON-RPC API for reading blockchain data.
|
||||
|
||||
### Endpoint
|
||||
|
||||
- **HTTPS**: `https://rpc.d-bis.org`
|
||||
- **WebSocket**: `wss://rpc.d-bis.org`
|
||||
- **Secondary HTTPS**: `https://rpc2.d-bis.org`
|
||||
- **Domain**: `d-bis.org` (Cloudflare DNS/SSL)
|
||||
|
||||
### Authentication
|
||||
|
||||
Currently, authentication is not required for public endpoints. API keys may be required in the future.
|
||||
|
||||
### Rate Limits
|
||||
|
||||
- **Default**: 1200 requests/minute per IP
|
||||
- **eth_call**: 600 requests/minute
|
||||
- **eth_getLogs**: 300 requests/minute
|
||||
- **eth_getBlockByNumber**: 600 requests/minute
|
||||
- **eth_getTransactionReceipt**: 600 requests/minute
|
||||
- **eth_estimateGas**: 300 requests/minute
|
||||
|
||||
### Allowed Methods
|
||||
|
||||
#### Read Operations
|
||||
|
||||
- `eth_blockNumber` - Get current block number
|
||||
- `eth_call` - Execute a message call
|
||||
- `eth_estimateGas` - Estimate gas for a transaction
|
||||
- `eth_gasPrice` - Get current gas price
|
||||
- `eth_getBalance` - Get account balance
|
||||
- `eth_getBlockByHash` - Get block by hash
|
||||
- `eth_getBlockByNumber` - Get block by number
|
||||
- `eth_getBlockTransactionCountByHash` - Get transaction count in block
|
||||
- `eth_getBlockTransactionCountByNumber` - Get transaction count in block
|
||||
- `eth_getCode` - Get contract code
|
||||
- `eth_getLogs` - Get logs (limited to 10,000 blocks)
|
||||
- `eth_getStorageAt` - Get storage at address
|
||||
- `eth_getTransactionByHash` - Get transaction by hash
|
||||
- `eth_getTransactionByBlockHashAndIndex` - Get transaction by block and index
|
||||
- `eth_getTransactionByBlockNumberAndIndex` - Get transaction by block and index
|
||||
- `eth_getTransactionCount` - Get transaction count (nonce)
|
||||
- `eth_getTransactionReceipt` - Get transaction receipt
|
||||
- `eth_getUncleByBlockHashAndIndex` - Get uncle by block and index
|
||||
- `eth_getUncleByBlockNumberAndIndex` - Get uncle by block and index
|
||||
- `eth_getUncleCountByBlockHash` - Get uncle count by block hash
|
||||
- `eth_getUncleCountByBlockNumber` - Get uncle count by block number
|
||||
- `eth_protocolVersion` - Get protocol version
|
||||
- `eth_syncing` - Get sync status
|
||||
- `net_listening` - Check if node is listening
|
||||
- `net_peerCount` - Get peer count
|
||||
- `net_version` - Get network version
|
||||
- `web3_clientVersion` - Get client version
|
||||
- `web3_sha3` - Hash data with keccak256
|
||||
|
||||
#### Blocked Methods
|
||||
|
||||
The following methods are blocked for public users:
|
||||
|
||||
- `eth_sendTransaction` - Send transaction (write operation)
|
||||
- `eth_sendRawTransaction` - Send raw transaction (write operation)
|
||||
- `miner_*` - Mining operations
|
||||
- `admin_*` - Admin operations
|
||||
- `debug_*` - Debug operations (except limited trace operations)
|
||||
|
||||
### Request Format
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_blockNumber",
|
||||
"params": [],
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
### Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": "0x1234"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Format
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"error": {
|
||||
"code": -32000,
|
||||
"message": "execution reverted"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Get Block Number
|
||||
|
||||
```bash
|
||||
curl -X POST https://rpc.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_blockNumber",
|
||||
"params": [],
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
### Get Block by Number
|
||||
|
||||
```bash
|
||||
curl -X POST https://rpc.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_getBlockByNumber",
|
||||
"params": ["latest", false],
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
### Call Contract
|
||||
|
||||
```bash
|
||||
curl -X POST https://rpc.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_call",
|
||||
"params": [{
|
||||
"to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
|
||||
"data": "0x70a08231000000000000000000000000742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
|
||||
}, "latest"],
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
### Get Logs
|
||||
|
||||
```bash
|
||||
curl -X POST https://rpc.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_getLogs",
|
||||
"params": [{
|
||||
"fromBlock": "0x0",
|
||||
"toBlock": "latest",
|
||||
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
|
||||
"topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
|
||||
}],
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
## WebSocket API
|
||||
|
||||
### Connection
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('wss://rpc.d-bis.org');
|
||||
|
||||
ws.onopen = () => {
|
||||
ws.send(JSON.stringify({
|
||||
jsonrpc: "2.0",
|
||||
method: "eth_subscribe",
|
||||
params: ["newHeads"],
|
||||
id: 1
|
||||
}));
|
||||
};
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log(data);
|
||||
};
|
||||
```
|
||||
|
||||
## Chain Metadata
|
||||
|
||||
- **ChainID**: 138
|
||||
- **Network Name**: DeFi Oracle Meta Mainnet
|
||||
- **Native Currency**: ETH
|
||||
- **Block Time**: ~2 seconds
|
||||
- **Explorer**: https://explorer.d-bis.org
|
||||
|
||||
## Rate Limit Headers
|
||||
|
||||
When rate limits are approached, the following headers are included in responses:
|
||||
|
||||
- `X-RateLimit-Limit`: Maximum requests per minute
|
||||
- `X-RateLimit-Remaining`: Remaining requests in current window
|
||||
- `X-RateLimit-Reset`: Time when the rate limit resets
|
||||
|
||||
## Error Codes
|
||||
|
||||
- `-32700`: Parse error
|
||||
- `-32600`: Invalid request
|
||||
- `-32601`: Method not found
|
||||
- `-32602`: Invalid params
|
||||
- `-32603`: Internal error
|
||||
- `-32000`: Execution error
|
||||
- `-32001`: Resource not found
|
||||
- `-32002`: Resource unavailable
|
||||
- `-32003`: Transaction rejected
|
||||
- `-32004`: Method not supported
|
||||
- `-32005`: Limit exceeded
|
||||
|
||||
## Support
|
||||
|
||||
For API support, please contact the network operators or open an issue on the project repository.
|
||||
|
||||
212
docs/api/API_REFERENCE.md
Normal file
212
docs/api/API_REFERENCE.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# API Reference
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
**Status**: Active
|
||||
**Base URL**: `https://rpc.d-bis.org`
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Authentication](#authentication)
|
||||
- [JSON-RPC Methods](#json-rpc-methods)
|
||||
- [Request/Response Format](#requestresponse-format)
|
||||
- [Error Handling](#error-handling)
|
||||
- [Rate Limits](#rate-limits)
|
||||
- [Examples](#examples)
|
||||
|
||||
## Overview
|
||||
|
||||
This API provides JSON-RPC 2.0 endpoints for interacting with the DeFi Oracle Meta Mainnet (ChainID 138).
|
||||
|
||||
## Authentication
|
||||
|
||||
Currently, the public RPC endpoint does not require authentication. Rate limiting is applied per IP address.
|
||||
|
||||
> **Note**: For production applications, consider using authenticated endpoints or API keys.
|
||||
|
||||
## JSON-RPC Methods
|
||||
|
||||
### Standard Ethereum Methods
|
||||
|
||||
All standard Ethereum JSON-RPC methods are supported. See [Ethereum JSON-RPC Specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) for complete reference.
|
||||
|
||||
#### Common Methods
|
||||
|
||||
- `eth_blockNumber` - Get latest block number
|
||||
- `eth_getBalance` - Get account balance
|
||||
- `eth_getTransactionCount` - Get transaction count (nonce)
|
||||
- `eth_sendTransaction` - Send transaction
|
||||
- `eth_call` - Execute call without creating transaction
|
||||
- `eth_getTransactionReceipt` - Get transaction receipt
|
||||
- `eth_getLogs` - Get event logs
|
||||
|
||||
### Example Request
|
||||
|
||||
```bash
|
||||
curl -X POST https://rpc.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_blockNumber",
|
||||
"params": [],
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
### Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": "0x12345"
|
||||
}
|
||||
```
|
||||
|
||||
## Request/Response Format
|
||||
|
||||
### Request Format
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "method_name",
|
||||
"params": [param1, param2],
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
### Response Format
|
||||
|
||||
**Success**:
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": "result_data"
|
||||
}
|
||||
```
|
||||
|
||||
**Error**:
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"error": {
|
||||
"code": -32000,
|
||||
"message": "Error message"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Error Codes
|
||||
|
||||
| Code | Meaning | Description |
|
||||
|------|---------|-------------|
|
||||
| -32700 | Parse error | Invalid JSON |
|
||||
| -32600 | Invalid Request | JSON is not a valid request |
|
||||
| -32601 | Method not found | Method does not exist |
|
||||
| -32602 | Invalid params | Invalid method parameters |
|
||||
| -32603 | Internal error | Internal JSON-RPC error |
|
||||
| -32000 | Server error | Generic server error |
|
||||
| -32001 | Rate limit | Rate limit exceeded |
|
||||
|
||||
### Error Response Example
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"error": {
|
||||
"code": -32001,
|
||||
"message": "Rate limit exceeded",
|
||||
"data": {
|
||||
"limit": 1200,
|
||||
"window": "1 minute"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
- **Default**: 1200 requests per minute per IP
|
||||
- **eth_call**: 600 requests per minute
|
||||
- **eth_getLogs**: 300 requests per minute
|
||||
- **eth_getBlockByNumber**: 600 requests per minute
|
||||
|
||||
Rate limit headers are included in responses:
|
||||
- `X-RateLimit-Limit`: Maximum requests allowed
|
||||
- `X-RateLimit-Remaining`: Remaining requests in window
|
||||
- `X-RateLimit-Reset`: Time when limit resets
|
||||
|
||||
## Examples
|
||||
|
||||
### Get Latest Block Number
|
||||
|
||||
```bash
|
||||
curl -X POST https://rpc.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_blockNumber",
|
||||
"params": [],
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
### Get Account Balance
|
||||
|
||||
```bash
|
||||
curl -X POST https://rpc.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_getBalance",
|
||||
"params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "latest"],
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
### Call Contract Method
|
||||
|
||||
```bash
|
||||
curl -X POST https://rpc.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_call",
|
||||
"params": [{
|
||||
"to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
|
||||
"data": "0x70a08231000000000000000000000000742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
|
||||
}, "latest"],
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
### Get Transaction Receipt
|
||||
|
||||
```bash
|
||||
curl -X POST https://rpc.d-bis.org \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "eth_getTransactionReceipt",
|
||||
"params": ["0x1234567890abcdef..."],
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [API Overview](API.md)
|
||||
- [Blockscout API](BLOCKSCOUT_API.md)
|
||||
- [Tatum SDK](TATUM_SDK.md)
|
||||
- [Integration Guide](../guides/INTEGRATION_GUIDE.md)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
300
docs/api/BLOCKSCOUT_API.md
Normal file
300
docs/api/BLOCKSCOUT_API.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# Blockscout API Documentation
|
||||
|
||||
API endpoints for Blockscout explorer on ChainID 138.
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
https://explorer.d-bis.org
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Token Metadata
|
||||
|
||||
#### Get Token Information
|
||||
|
||||
```
|
||||
GET /api/v2/tokens/{address}
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `address` (path): Token contract address
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"address": "0x...",
|
||||
"name": "Wrapped Ether",
|
||||
"symbol": "WETH",
|
||||
"decimals": 18,
|
||||
"total_supply": "1000000000000000000000",
|
||||
"holders_count": 100,
|
||||
"transactions_count": 1000
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Token Holders
|
||||
|
||||
```
|
||||
GET /api/v2/tokens/{address}/holders
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `address` (path): Token contract address
|
||||
- `page` (query): Page number (default: 1)
|
||||
- `offset` (query): Items per page (default: 50)
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"address": "0x...",
|
||||
"value": "100000000000000000000",
|
||||
"token": {
|
||||
"address": "0x...",
|
||||
"symbol": "WETH",
|
||||
"decimals": 18
|
||||
}
|
||||
}
|
||||
],
|
||||
"next_page_path": "/api/v2/tokens/{address}/holders?page=2"
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Token Transfers
|
||||
|
||||
```
|
||||
GET /api/v2/tokens/{address}/transfers
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `address` (path): Token contract address
|
||||
- `page` (query): Page number (default: 1)
|
||||
- `offset` (query): Items per page (default: 50)
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"from": {
|
||||
"hash": "0x...",
|
||||
"name": null
|
||||
},
|
||||
"to": {
|
||||
"hash": "0x...",
|
||||
"name": null
|
||||
},
|
||||
"total": {
|
||||
"value": "100000000000000000000",
|
||||
"token": {
|
||||
"address": "0x...",
|
||||
"symbol": "WETH",
|
||||
"decimals": 18
|
||||
}
|
||||
},
|
||||
"tx_hash": "0x...",
|
||||
"timestamp": "2024-12-19T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"next_page_path": "/api/v2/tokens/{address}/transfers?page=2"
|
||||
}
|
||||
```
|
||||
|
||||
### Account Information
|
||||
|
||||
#### Get Account Balance
|
||||
|
||||
```
|
||||
GET /api/v2/addresses/{address}
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `address` (path): Account address
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"hash": "0x...",
|
||||
"balance": "1000000000000000000000",
|
||||
"tx_count": 100,
|
||||
"token_count": 10
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Account Tokens
|
||||
|
||||
```
|
||||
GET /api/v2/addresses/{address}/token-balances
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `address` (path): Account address
|
||||
- `page` (query): Page number (default: 1)
|
||||
- `offset` (query): Items per page (default: 50)
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"address": "0x...",
|
||||
"value": "100000000000000000000",
|
||||
"token": {
|
||||
"address": "0x...",
|
||||
"name": "Wrapped Ether",
|
||||
"symbol": "WETH",
|
||||
"decimals": 18,
|
||||
"logo_url": "https://explorer.d-bis.org/images/tokens/weth.png"
|
||||
}
|
||||
}
|
||||
],
|
||||
"next_page_path": "/api/v2/addresses/{address}/token-balances?page=2"
|
||||
}
|
||||
```
|
||||
|
||||
### Contract Verification
|
||||
|
||||
#### Get Contract Source Code
|
||||
|
||||
```
|
||||
GET /api/v2/smart-contracts/{address}
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `address` (path): Contract address
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"address": "0x...",
|
||||
"name": "WETH",
|
||||
"compiler_version": "0.8.19",
|
||||
"optimization": true,
|
||||
"source_code": "// SPDX-License-Identifier: MIT\n...",
|
||||
"abi": [...],
|
||||
"verified": true
|
||||
}
|
||||
```
|
||||
|
||||
## CORS Configuration
|
||||
|
||||
Blockscout must allow CORS requests from:
|
||||
|
||||
- `https://portfolio.metamask.io` (MetaMask Portfolio)
|
||||
- `https://metamask.io` (MetaMask website)
|
||||
- `https://chainlist.org` (Chainlist)
|
||||
|
||||
### CORS Headers
|
||||
|
||||
```
|
||||
Access-Control-Allow-Origin: https://portfolio.metamask.io
|
||||
Access-Control-Allow-Methods: GET, OPTIONS
|
||||
Access-Control-Allow-Headers: Content-Type
|
||||
Access-Control-Max-Age: 3600
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
### Limits
|
||||
|
||||
- **Default**: 120 requests/minute per IP
|
||||
- **API Keys**: Higher limits for API key holders
|
||||
- **Public**: Lower limits for public access
|
||||
|
||||
### Headers
|
||||
|
||||
```
|
||||
X-RateLimit-Limit: 120
|
||||
X-RateLimit-Remaining: 100
|
||||
X-RateLimit-Reset: 1638360000
|
||||
```
|
||||
|
||||
## Token Logo Serving
|
||||
|
||||
### Logo URL Format
|
||||
|
||||
```
|
||||
https://explorer.d-bis.org/images/tokens/{address}.png
|
||||
```
|
||||
|
||||
### Fallback
|
||||
|
||||
If token logo is not found, use default token logo or logo from token list.
|
||||
|
||||
### Supported Formats
|
||||
|
||||
- PNG (preferred)
|
||||
- SVG
|
||||
- JPEG
|
||||
|
||||
### Size Requirements
|
||||
|
||||
- **Recommended**: 512x512 pixels
|
||||
- **Minimum**: 128x128 pixels
|
||||
- **Maximum**: 1024x1024 pixels
|
||||
|
||||
## MetaMask Portfolio Integration
|
||||
|
||||
### Required Endpoints
|
||||
|
||||
For MetaMask Portfolio to display tokens:
|
||||
|
||||
1. **Token Metadata**: `/api/v2/tokens/{address}`
|
||||
2. **Token Holders**: `/api/v2/tokens/{address}/holders`
|
||||
3. **Account Tokens**: `/api/v2/addresses/{address}/token-balances`
|
||||
4. **Token Transfers**: `/api/v2/tokens/{address}/transfers`
|
||||
|
||||
### CORS Requirements
|
||||
|
||||
Blockscout must allow CORS from Portfolio domain.
|
||||
|
||||
### Token List Integration
|
||||
|
||||
Portfolio uses token lists for auto-detection. Ensure token metadata matches token list entries.
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Error Responses
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Error message",
|
||||
"status": 400
|
||||
}
|
||||
```
|
||||
|
||||
### Common Errors
|
||||
|
||||
- **400 Bad Request**: Invalid parameters
|
||||
- **404 Not Found**: Resource not found
|
||||
- **429 Too Many Requests**: Rate limit exceeded
|
||||
- **500 Internal Server Error**: Server error
|
||||
|
||||
## Examples
|
||||
|
||||
### Get WETH Token Information
|
||||
|
||||
```bash
|
||||
curl https://explorer.d-bis.org/api/v2/tokens/0xYourWETHAddress
|
||||
```
|
||||
|
||||
### Get Account Token Balances
|
||||
|
||||
```bash
|
||||
curl https://explorer.d-bis.org/api/v2/addresses/0xYourAddress/token-balances
|
||||
```
|
||||
|
||||
### Get Token Holders
|
||||
|
||||
```bash
|
||||
curl https://explorer.d-bis.org/api/v2/tokens/0xYourTokenAddress/holders
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Blockscout API Documentation](https://docs.blockscout.com/for-developers/api)
|
||||
- [Blockscout GitHub](https://github.com/blockscout/blockscout)
|
||||
|
||||
271
docs/api/TATUM_SDK.md
Normal file
271
docs/api/TATUM_SDK.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# Tatum SDK Integration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The Tatum SDK provides a convenient interface for interacting with the DeFi Oracle Meta Mainnet (ChainID 138) while using your own RPC endpoints. This guide explains how to integrate and use the Tatum SDK with ChainID 138.
|
||||
|
||||
## Important Notes
|
||||
|
||||
**Key Limitations:**
|
||||
- With custom RPC, **only RPC calls are redirected to your node**
|
||||
- Tatum's cloud services (Notifications, Blockchain Data, etc.) **won't work** on unsupported/private chains
|
||||
- Only raw JSON-RPC calls will work
|
||||
- Transactions must be signed with `chainId: 138` (EIP-155)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **RPC Endpoint Access**
|
||||
- Your ChainID 138 RPC node must be accessible
|
||||
- HTTP RPC at port 8545
|
||||
- WebSocket RPC at port 8546 (optional)
|
||||
|
||||
2. **Node.js Environment**
|
||||
- Node.js 18+ recommended
|
||||
- npm or yarn package manager
|
||||
|
||||
3. **Network Configuration**
|
||||
- ChainID 138 configured in genesis
|
||||
- RPC nodes deployed and running
|
||||
- Network connectivity verified
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
cd sdk
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Update `.env` with your RPC endpoint:
|
||||
|
||||
```env
|
||||
RPC_URL=https://rpc.d-bis.org
|
||||
WS_URL=wss://rpc.d-bis.org
|
||||
EXPLORER_URL=https://explorer.d-bis.org
|
||||
PRIVATE_KEY=your-private-key-here
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### Initialize Tatum SDK
|
||||
|
||||
```typescript
|
||||
import { initTatumSDK, verifyConnection } from './tatum-client';
|
||||
|
||||
// Initialize with custom RPC URL
|
||||
const tatum = await initTatumSDK({
|
||||
rpcUrl: 'https://rpc.d-bis.org',
|
||||
verbose: true,
|
||||
});
|
||||
|
||||
// Verify connection and chain ID
|
||||
const connectionInfo = await verifyConnection(tatum);
|
||||
console.log('Chain ID:', connectionInfo.chainId); // Should be 138
|
||||
console.log('Current Block:', connectionInfo.blockNumber);
|
||||
```
|
||||
|
||||
### Make RPC Calls
|
||||
|
||||
```typescript
|
||||
// Get block number
|
||||
const blockNumber = await tatum.rpc.request('eth_blockNumber', []);
|
||||
|
||||
// Get chain ID
|
||||
const chainId = await tatum.rpc.request('eth_chainId', []);
|
||||
|
||||
// Get gas price
|
||||
const gasPrice = await tatum.rpc.request('eth_gasPrice', []);
|
||||
|
||||
// Get balance
|
||||
const balance = await tatum.rpc.request('eth_getBalance', [
|
||||
'0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
|
||||
'latest'
|
||||
]);
|
||||
```
|
||||
|
||||
## Sending Transactions
|
||||
|
||||
### Using ethers.js
|
||||
|
||||
```typescript
|
||||
import { ethers } from 'ethers';
|
||||
import { CHAIN_ID, DEFAULT_RPC_URL } from './config';
|
||||
|
||||
// Initialize provider with ChainID 138
|
||||
const provider = new ethers.JsonRpcProvider(DEFAULT_RPC_URL, {
|
||||
chainId: CHAIN_ID,
|
||||
name: 'defi-oracle-mainnet',
|
||||
});
|
||||
|
||||
// Create wallet
|
||||
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);
|
||||
|
||||
// Send transaction (must include chainId: 138)
|
||||
const tx = await wallet.sendTransaction({
|
||||
to: '0xRecipientAddress...',
|
||||
value: ethers.parseEther('0.01'),
|
||||
chainId: CHAIN_ID, // Important: Must be 138
|
||||
});
|
||||
|
||||
// Wait for confirmation
|
||||
const receipt = await tx.wait();
|
||||
console.log('Transaction confirmed:', receipt.blockNumber);
|
||||
```
|
||||
|
||||
### Verify Chain ID in Transaction
|
||||
|
||||
```typescript
|
||||
// Get transaction from chain
|
||||
const txFromChain = await tatum.rpc.request('eth_getTransactionByHash', [tx.hash]);
|
||||
|
||||
// Verify chainId
|
||||
if (txFromChain && typeof txFromChain === 'object' && 'chainId' in txFromChain) {
|
||||
const txChainId = parseInt(txFromChain.chainId as string, 16);
|
||||
if (txChainId === 138) {
|
||||
console.log('✓ ChainID verified');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Contract Deployment
|
||||
|
||||
```typescript
|
||||
import { ethers } from 'ethers';
|
||||
import { CHAIN_ID, DEFAULT_RPC_URL } from './config';
|
||||
|
||||
// Initialize provider
|
||||
const provider = new ethers.JsonRpcProvider(DEFAULT_RPC_URL, {
|
||||
chainId: CHAIN_ID,
|
||||
name: 'defi-oracle-mainnet',
|
||||
});
|
||||
|
||||
// Create wallet
|
||||
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);
|
||||
|
||||
// Deploy contract
|
||||
const factory = new ethers.ContractFactory(ABI, BYTECODE, wallet);
|
||||
const contract = await factory.deploy({
|
||||
chainId: CHAIN_ID, // Important: Must be 138
|
||||
});
|
||||
|
||||
await contract.waitForDeployment();
|
||||
const contractAddress = await contract.getAddress();
|
||||
console.log('Contract deployed at:', contractAddress);
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Run Connection Test
|
||||
|
||||
```bash
|
||||
npm run test
|
||||
```
|
||||
|
||||
### Run Smoke Test
|
||||
|
||||
```bash
|
||||
npm run smoke-test
|
||||
```
|
||||
|
||||
### Run Examples
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
npm run example:basic
|
||||
|
||||
# Send transaction
|
||||
npm run example:transaction
|
||||
|
||||
# Deploy contract
|
||||
npm run example:contract
|
||||
```
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] RPC node is up and accessible
|
||||
- [ ] ChainID is 138 (0x8a in hex)
|
||||
- [ ] Tatum SDK initialized with custom `rpcUrl`
|
||||
- [ ] Transactions signed with `chainId: 138`
|
||||
- [ ] RPC calls are working correctly
|
||||
- [ ] Network connectivity verified
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
|
||||
**Problem**: RPC endpoint not responding
|
||||
|
||||
**Solutions**:
|
||||
1. Verify RPC node is running: `kubectl get pods -n besu-network`
|
||||
2. Check network connectivity: `curl -X POST $RPC_URL -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'`
|
||||
3. Verify firewall/network settings
|
||||
4. Check RPC_URL in .env file
|
||||
|
||||
### Chain ID Mismatch
|
||||
|
||||
**Problem**: Chain ID mismatch errors
|
||||
|
||||
**Solutions**:
|
||||
1. Verify genesis file has `chainId: 138`
|
||||
2. Check node configuration
|
||||
3. Ensure all transactions use `chainId: 138`
|
||||
4. Verify `eth_chainId` returns `0x8a` (138 in hex)
|
||||
|
||||
### Transaction Failures
|
||||
|
||||
**Problem**: Transactions failing
|
||||
|
||||
**Solutions**:
|
||||
1. Verify `chainId: 138` is set in transaction
|
||||
2. Check account has sufficient balance
|
||||
3. Verify gas price and limits
|
||||
4. Check transaction nonce
|
||||
5. Review node logs for errors
|
||||
|
||||
## Limitations
|
||||
|
||||
As per Tatum documentation:
|
||||
|
||||
1. **Cloud Services**: Tatum's cloud services (Notifications, Blockchain Data, etc.) won't work with custom RPC endpoints
|
||||
2. **Indexer Support**: No indexer support for private chains
|
||||
3. **RPC Only**: Only raw JSON-RPC calls are available
|
||||
4. **No Webhooks**: Webhook notifications won't work
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always set chainId**: Always include `chainId: 138` in transactions
|
||||
2. **Verify connection**: Always verify connection and chain ID before making calls
|
||||
3. **Error handling**: Implement proper error handling for RPC calls
|
||||
4. **Rate limiting**: Be aware of RPC rate limits
|
||||
5. **Gas estimation**: Always estimate gas before sending transactions
|
||||
|
||||
## Examples
|
||||
|
||||
See the `sdk/src/examples/` directory for complete examples:
|
||||
|
||||
- `basic-usage.ts`: Basic connection and querying
|
||||
- `send-transaction.ts`: Sending transactions
|
||||
- `deploy-contract.ts`: Deploying and interacting with contracts
|
||||
|
||||
## References
|
||||
|
||||
- [Tatum SDK Documentation](https://docs.tatum.io/docs/configuration-options)
|
||||
- [Ethereum JSON-RPC API](https://ethereum.org/developers/docs/apis/json-rpc/)
|
||||
- [EIP-155: Simple replay attack protection](https://eips.ethereum.org/EIPS/eip-155)
|
||||
- [Besu JSON-RPC API](https://besu.hyperledger.org/en/stable/Reference/API-Methods/)
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
1. Check the troubleshooting section
|
||||
2. Review the examples in `sdk/src/examples/`
|
||||
3. Open an issue on the project repository
|
||||
4. Contact the network operators
|
||||
|
||||
Reference in New Issue
Block a user