Filecoin API - Schema and usage guide

INTRODUCTION

The following document describes and exemplifies the usage of the tables generated by the Filecoin chain indexing project. The tables described below, are the result of indexing the entire Filecoin chain focusing on getting transactional data relevant for making financial reports or statements. The way to access this API is trough GraphQL queries.

ADDRESSES

The addresses table maps robust-form addresses (f1, f2, f3) with their ID address equivalent (f0) and contains information on the account type.

(Explainer on Filecoin addresses: link)

Table description:

Column name	Description
robust	Robust form for a Filecoin address (BLS, SECP256K1 and Actor addresses starting with f1, f2, f3)
short	Short (ID) form for a Filecoin address, starting with f0
actor_type	Account type (account, payment channel, miner, etc)
id	Additional field to aid with ordering and foreign key constraints

Example GraphQL query

“Convert” an address (look up the address in the short/robust format)

query AddressesGetRobustByShort {
  finance_addresses(where: {short: {_eq: "f025..."}}) {
    robust
  }
}

query AddressesGetShortByRobust {
  finance_addresses(where: {robust: {_eq: "f3u4awxhbhz7jb..."}}) {
    short
  }
}

TRANSACTIONS

The transactions table contains the transactions made by every address across the entire Filecoin blockchain history. The following table shows the currently supported Actors and their methods:

Actor	Methods
Common	Send, Fee
Init	Exec
Multisig	SwapSigner, AddSigner, RemoveSigner, Propose, Approve, Cancel
Reward	AwardBlockReward
Miner	OnDeferredCronEvent, PreCommitSector, ProveCommitSector, SubmitWindowedPoSt, ApplyRewards, WithdrawBalance,ChangeOwnerAddress, ChangeWorkerAddress, ConfirmUpdateWorkerKey
Power	CreateMiner
Market	AddBalance
VerifiedRegistry	AddVerifiedClient, AddVerifier, RemoveVerifier

Table description:

Column name	Description
height	Tipset height at which the transaction’s block is located
tx_timestamp	Tipset and block timestamp in UNIX format
tx_hash	Transaction hash (identifier)
tx_from	Sender address
tx_to	Receiver address
amount	Transaction value [FIL]
status	Transaction status (if the transaction was successful or not)
tx_type	Transaction type (method name)
tx_metadata (optional)	Includes additional info on the Tx (currently this refers to the method of the Tx a fee belongs to)
tx_params (optional)	If any additional user-generated input has been added to the Tx (currently parsed params are only available for Txs with the following format: PREFIX:WHATEVER )

Note

For each transaction, the fees in this table are divided in OverEstimationBurn, BurnFee and MinerFee. The total fee can be calculated as:

TotalFee = OverEstimationBurn + BurnFee + MinerFee

Example GraphQL query

Find all transactions in which a certain address has participated:

query TransactionsGetByAddress {
  finance_transactions(where: {_or: 
  [{tx_from: {_eq: "f3rrwmsdclcwsy3prwjd..."}}, 
  {tx_from: {_eq: "f0869..."}}]}) {
    tx_from
    amount
    height
    status
    tx_hash
    tx_metadata
    tx_params
    tx_timestamp
    tx_to
    tx_type
  }
}

Get transactions at a certain height:

query TransactionsGetByHeight {
  finance_transactions(where: {height: {_eq: "231866"}}) {
    amount
    height
    status
    tx_from
    tx_hash
    tx_metadata
    tx_params
    tx_to
    tx_type
  }
}

Filter by a tx_params prefix:

query TransactionsGetByParams {
  finance_transactions(where: {tx_params: {_like: "SOMEPREFIX%"}}) {
    amount
    height
    status
    tx_from
    tx_hash
    tx_metadata
    tx_params
    tx_to
    tx_type
  }
}

Find all the fees collected by some miner:

query GetMinerCollectedFees {
  finance_transactions(where: {_and: 
  [{tx_to: {_eq: "f032..."}}, 
  {tx_type: {_eq: "MinerFee"}}]}) {
    tx_from
    amount
    height
    status
    tx_hash
    tx_metadata
    tx_params
    tx_timestamp
    tx_to
    tx_type
  }
}

VESTING

The vesting table contains vesting details for multisig wallets.

Table description:

Column name	Description
address	Filecoin account address
initial_balance	Inicial locked vesting amount [FIL]
start_epoch	Tipset height in which the vesting period starts
unlock_duration	How many block epochs it will take to unlock the full amount
unlock_height	Tipset height at which the full vesting amount will be released (calculated as start_epoch + unlock_duration)

Example GraphQL query

Look up vesting data for an address

query VestingGetByAddress {
  finance_vesting(where: {address: {_eq: "f096..."}}) {
    address
    initial_balance
    start_epoch
    unlock_duration
    unlock_height
  }
}

BLOCKS_DATES

Auxiliary table to simplify querying by tipset date (as the dates are stored in a human-readable format instead of a UNIX timestamp)

Table description:

Column name	Description
height	Tipset height
timestamp	UTC date with the format YYYY-MM-DD hh:mm:ss

Example GraphQL query

Get the timestamp of a tipset

query GetTipsetTimestamp {
  finance_blocks_dates(where: {height: {_eq: 100310}}) {
    timestamp
  }
}

MSIG_TRANSACTIONS

The msig_transactions table contains detailed information about the transactions that interacted with multisig addresses.

The following list shows the current supported multisig methods:

"SwapSigner", "AddSigner", "RemoveSigner",
"Propose", "Approve", "Cancel", "Send", "Exec"

Table description:

Column name	Description
height	Tipset height
hx_hash	Transaction hash (identifier)
tx_from	Sender address
multisig	Target multisig address
proposed_method	Method being proposed to be executed by the multisig
signer_in	(In AddSigner Txs) Signer that has been added to the multisig wallet
signer_out	(In RemoveSigner Txs) Signer that has been removed from the multisig wallet
tx_type	Multisig transaction type (method name)
tx_value	Transaction value proposed or transferred
status	Transaction status (if the transaction was successful or not)

Example GraphQL query

Find all multisigs address where an address is a signer (or has been proposed as a signer)

query MsigTransactionsGetByAddedSigner {
  finance_msig_transactions(where: {signer_in: {_eq: "f3vqxn4nq..."}}) {
    multisig
  }
}

Find all multisigs where an address has been removed as a signer

query MsigTransactionsGetByRemovedSigner {
  finance_msig_transactions(where: 
    {signer_out: {_eq: "f020..."}, tx_type: {_in: ["RemoveSigner", "SwapSigner"]}}) {
        multisig
  }
}