Skip to content
Last updated

Standards

Vilna uses CAIP identifiers for chains, accounts and assets, and RFC 7807 for HTTP API errors.

CAIP-2 chains CAIP-10 accounts CAIP-19 assets RFC 7807 errors

CAIP - chain-agnostic identifiers

CAIP (Chain Agnostic Improvement Proposals) gives every blockchain, account and asset one identifier shape - so the same code path handles Ethereum, Bitcoin and Solana without per-chain special cases. In a Vilna response, a record points at a chain, an address or a token with one of these ids.

There are three levels, and each builds on the one before it: an account is a chain plus an address; an asset is a chain plus an asset descriptor.

CAIP-2 - the blockchain

The base identifier. It names a chain in two parts:

namespace

The chain family - eip155 for EVM chains, bip122 for Bitcoin-like, plus solana, cosmos and more.

e.g. eip155
reference

The specific chain inside that family - the chain ID for EVM, the genesis block hash for Bitcoin.

e.g. 1
ChainCAIP-2
Ethereum Mainneteip155:1
BNB Smart Chaineip155:56
Polygoneip155:137
Arbitrum Oneeip155:42161
Bitcoinbip122:000000000019d6689c085ae165831e93
Solanasolana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp

CAIP-10 - an account

An address on a specific chain - take a CAIP-2 id and append the address:

chain_id

Any CAIP-2 blockchain id - the chain the account lives on.

e.g. eip155:1
address

The address on that chain, in its native format (hex for EVM, base58 for Bitcoin and Solana).

e.g. 0x742d35Cc…7B123
eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f7B123

CAIP-19 - an asset

Any asset - native coin, token or NFT. It joins a CAIP-2 chain to an asset descriptor with a /:

chain_id

Any CAIP-2 blockchain id - the chain the asset lives on.

e.g. eip155:1
asset_namespace

The asset type - slip44 for a native coin, erc20 for a fungible token, erc721 / erc1155 for NFTs.

e.g. erc20
asset_reference

The asset within that type - a contract address for tokens, or a coin type for native currencies.

e.g. 0xdAC17F…1ec7
AssetCAIP-19
ETH (native)eip155:1/slip44:60
BTC (native)bip122:000000000019d6689c085ae165831e93/slip44:0
USDT on Ethereumeip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7
USDC on Ethereumeip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
BAYC #101 (NFT)eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/101

Native currencies use the coin type from the SLIP-44 registry (60 = ETH, 0 = BTC); tokens and NFTs use the contract address, with the token id appended for a single NFT.

RFC 7807 - error format

The Platform, Management and VKS HTTP APIs use RFC 7807 Problem Details (application/problem+json). See Errors for fields, service-specific extensions and recovery guidance. Blockchain RPC uses its protocol error model.

References

Networks