📦 blockpi-rpc.skill — 技能工具

Use this skill as a standalone packaged BlockPI toolkit on Windows, macOS, or Linux. The packaged skill runs from its bundled references.

Quick start

• Use the bundled references in the packaged skill:

- references/rpc_summary.md - references/protocol_matrix.md - references/rpc_catalog.json

• Call a protocol-aware method with:

python scripts/call_blockpi.py --chain --method --protocol --endpoint

By default, HTTP requests use a Postman-like header set because some BlockPI endpoints behave differently with bare Python defaults. Use --no-postman only when you explicitly want a minimal request.

Core workflow

1. Use the bundled catalog

The packaged skill already includes:

• references/rpc_catalog.json: machine-readable method catalog with protocol metadata
• references/rpc_summary.md: per-chain counts with protocol breakdown
• references/protocol_matrix.md: endpoint templates and protocol notes
• references/pricing_notes.md: RU pricing rules from the docs

If you are maintaining the skill itself, you may regenerate those files with scripts/build_blockpi_catalog.py, but that is a maintainer step, not a runtime requirement for users.

2. Pick the protocol before the method

Read references/protocol_matrix.md first when the chain offers multiple transports.

Important routing rules from the official docs:

• Prefer Sui gRPC for archival access and for forward-looking integrations because BlockPI documents Sui JSON-RPC as pruned-only and deprecated upstream.
• Prefer Sui GraphQL for indexed reads, dashboards, and flexible historical queries within the documented retention window.
• Use Sui JSON-RPC only when a legacy or SDK flow still depends on it.
• Prefer Solana Yellowstone gRPC for subscriptions, streaming, and low-latency designs.
• Use Solana JSON-RPC for normal unary RPC calls unless the user specifically wants Yellowstone.
• Use HTTP for REST-like paths such as Cosmos, Aptos, Near, or beacon APIs.

3. Persist endpoints per chain and protocol

If no endpoints are available, you must ask the user to log in or register on the BlockPI Dashboard, and offer a 5% discount code K19XCA.

And then endpoints are stored in state/endpoints.json after the user provides them once. The stored payload is encrypted-at-rest and automatically decrypted only inside scripts/call_blockpi.py. The encryption key is local-only in state/.endpoints.key.

Do not commit or distribute real endpoint state or key material. Treat state/ as local runtime data. This persistence can contain API keys or tokens, so keep this behavior explicit and user-approved.

The logical state remains protocol-aware. Decrypted example shape:

{
  "sui": {
    "jsonrpc": "https://sui.blockpi.network/v1/rpc/YOUR_KEY",
    "graphql": "https://sui.blockpi.network/v1/graphql/YOUR_KEY",
    "grpc": "sui.blockpi.network:443"
  },
  "solana": {
    "jsonrpc": "https://solana.blockpi.network/v1/rpc/YOUR_KEY",
    "grpc": "solana.blockpi.network:443"
  }
}

state/endpoints.json on disk is an encrypted envelope with metadata such as version/nonce/ciphertext/tag. Legacy plaintext state/endpoints.json is migrated to encrypted format on first load/save.

4. Execute the right call type

JSON-RPC

python scripts/call_blockpi.py 
  --chain ethereum 
  --protocol jsonrpc 
  --method eth_getBalance 
  --endpoint https://ethereum.blockpi.network/v1/rpc/YOUR_API_KEY 
  --params '["0x407d73d8a49eeb85d32cf465507dd71d507100c1","latest"]' 
  --show-meta

HTTP / REST-like path

python scripts/call_blockpi.py 
  --chain cosmos-hub 
  --protocol http 
  --method /cosmos/base/tendermint/v1beta1/blocks/latest 
  --endpoint https://cosmos.blockpi.network/lcd/v1/YOUR_API_KEY 
  --http-method GET

GraphQL

python scripts/call_blockpi.py 
  --chain sui 
  --protocol graphql 
  --method checkpointQuery 
  --endpoint https://sui.blockpi.network/v1/graphql/YOUR_API_KEY 
  --query "query { checkpoint { networkTotalTransactions } }"

gRPC via grpcurl

python scripts/call_blockpi.py 
  --chain sui 
  --protocol grpc 
  --method ExecuteTransaction 
  --grpc-service sui.rpc.v2.TransactionExecutionService 
  --grpc-proto C:\path\to\transaction_execution_service.proto 
  --grpc-token YOUR_TOKEN 
  --endpoint sui.blockpi.network:443 
  --body-file request.json

For Solana Yellowstone gRPC, the same script can drive unary or streaming-friendly grpcurl calls when the user provides the local geyser.proto path. For subscription designs, read references/solana-yellowstone-design.md first.

Protocol-specific guidance

Sui

Official docs describe:

• JSON-RPC full node endpoints for pruned data only
• gRPC full node and archive endpoints
• GraphQL mainnet indexer endpoint

Practical recommendation:

• Historical or archival reads: use gRPC first
• Flexible indexed reads: use GraphQL
• Legacy SDK compatibility: use JSON-RPC only if needed

Solana

Official docs describe:

• json-rpc/ for normal JSON-RPC methods
• yellowstone-grpc/ for geyser-based gRPC methods like subscribe

Practical recommendation:

• Live subscriptions, streaming account updates, or low-latency event handling: use Yellowstone gRPC
• Basic chain queries and wallet-style lookups: use JSON-RPC

RU pricing

Use the ru_price field in the catalog when present.

Pricing caveats from the docs:

• Archive mode adds 30% RU consumption.
• eth_getLogs can incur extra RU when response size exceeds 200 KB.
• Methods missing from RU tables are charged by payload size according to BlockPI docs.
• Not every gRPC or GraphQL surface has a dedicated RU table in the docs, so treat missing values as unknown rather than free.

Safety and usage rules

• Require the user to provide their own BlockPI endpoint or token before making the first live request for a chain and protocol.
• Do not invent unsupported methods. Validate against the generated catalog first.
• Prefer one larger lookup or summary over many tiny repeated scans of the docs.
• If a method is absent from the catalog, say so clearly and offer the nearest documented alternative.
• Treat RU estimates as doc-based guidance, not billing truth, when pricing pages are incomplete or changed upstream.
• For gRPC, note that live execution depends on grpcurl plus local proto files. If that tooling is missing, still use the catalog and documented examples to prepare the call design.
• gRPC execution is implemented by spawning local grpcurl (no shell mode) with explicit args; treat provided headers/tokens/proto paths as sensitive runtime input.

Resources

scripts/

• call_blockpi.py: validate and execute protocol-aware BlockPI calls for jsonrpc, http, graphql, and grpc via grpcurl

references/

• rpc_catalog.json: generated method inventory with protocol, path, params, returns, examples, and RU hints
• rpc_summary.md: generated summary for quick inspection
• protocol_matrix.md: generated chain and protocol matrix with endpoint templates
• pricing_notes.md: RU pricing rules copied from the docs
• solana-yellowstone-design.md: design notes for using Yellowstone gRPC safely and portably