Schema Reference

Every entity exposed by the vault indexer, generated from the deployed schema.

Each entity has two resolvers:

• Singular — vault(id: "0x…") returns one record or null
• Plural — vaults(where:, orderBy:, orderDirection:, limit:, offset:) returns a page

A page always carries items, totalCount and pageInfo. limit caps at 1000; see Limits and gotchas before writing a client.

Types are lower-case

Ponder generates this API from the indexer's table definitions, so type names match the table names and are lower-case (vault, not Vault). The plural of stats is statss for the same reason — the generator appends an s.

Core vault

The vault lifecycle and the actors that secure it. These entities exist regardless of which DeFi application a vault is used with.

vault

One BTCVault and its full lifecycle state — a depositor’s native Bitcoin locked in a UTXO on the Bitcoin network. status is the authority on where it sits; the timestamp fields cover only part of the path.

Query with vault(…) or vaults(…).

Field	Type	Required	Notes
id	String!	yes
peginTxHash	String!	yes
depositor	String!	yes	Depositor address, lowercase hex. Filters are case-sensitive.
depositorBtcPubKey	String!	yes
vaultProvider	String!	yes
vaultProviderCommissionBps	Int!	yes
amount	BigInt!	yes	Vault size in satoshis.
applicationEntryPoint	String!	yes
status	vaultStatus	no	Where the vault is in its lifecycle. Treat this as authoritative; not every state has a timestamp.
inUse	Boolean!	yes	Whether the vault is currently pledged to an application.
ackCount	Int!	yes	How many of the security set have acknowledged. Reaches 6 when complete. A vault sitting at 0 is stalling, and usually expires with ack_timeout.
depositorSignedPeginTx	String!	yes
unsignedPrePeginTx	String!	yes
appVaultKeepersVersion	Int!	yes
universalChallengersVersion	Int!	yes
offchainParamsVersion	Int!	yes
proverCircuitVersion	Int!	yes
vaultCoreVersion	Int!	yes
referralCode	Int!	yes
depositorPayoutBtcAddress	String!	yes
btcPopSignature	String	no
depositorWotsPkHash	String	no
peginSigsPostedAt	BigInt	no	Unix seconds. Dates the signatures_collected state.
prePeginTxHash	String	no
htlcVout	Int!	yes
hashlock	String!	yes
secret	String	no
currentOwner	String	no
pendingAt	BigInt!	yes	Unix seconds. Dates the pending state.
verifiedAt	BigInt	no	Unix seconds. Dates the verified state.
activatedAt	BigInt	no	Unix seconds. Dates the available state.
expiredAt	BigInt	no	Unix seconds. Dates the expired state.
expirationReason	String	no	Why the peg-in expired, for example ack_timeout.
claimExpiredUntil	BigInt	no	A block number, not a timestamp, despite sitting among the timestamp fields. The contract sets it to the expiry block plus a grace period. Compare it against the block in _meta, never against a clock.
expiredClaimedAt	BigInt	no
blockNumber	BigInt!	yes
transactionHash	String!	yes
application	application	no

vaultStatus values: pending · signatures_collected · verified · available · redeemed · liquidated · expired · invalid · depositor_withdrawn

vaultActivity

Append-only event log. It records six of the nine vaultActivityType values — deposit, borrow, repay, redeem, liquidation and claim_expired. It is not a complete history of everything that happens to a vault. See Known data gaps.

Query with vaultActivity(…) or vaultActivitys(…).

Field	Type	Required	Notes
id	String!	yes
vaultId	String	no	Null on borrow and repay. Those events are scoped to an Aave position rather than to one vault. This is by design, not missing data.
depositor	String!	yes
type	vaultActivityType!	yes	In practice one of deposit, borrow, repay, redeem, liquidation, claim_expired. The enum also declares withdrawal, add_collateral and remove_collateral, but nothing writes them.
amount	BigInt!	yes	Satoshis except on borrow and repay, where it is denominated in the debt asset. Resolve debtReserveId against aaveReserve before formatting.
debtReserveId	BigInt	no	Set on borrow and repay. Join to aaveReserve for the debt asset symbol and decimals.
timestamp	BigInt!	yes	Unix seconds. Use with timestamp_gt as a sync watermark.
blockNumber	BigInt!	yes
transactionHash	String!	yes

vaultActivityType values: deposit · withdrawal · add_collateral · remove_collateral · liquidation · borrow · repay · redeem · claim_expired

vaultProvider

The depositor's Vault Provider: the operator that sets up, redeems and defends the BTCVault. A depositor can run their own.

Query with vaultProvider(…) or vaultProviders(…).

Field	Type	Required	Notes
id	String!	yes
btcPubKey	String!	yes
applicationEntryPoint	String!	yes
commissionBps	Int!	yes	Basis points. 100 is 1%.
name	String	no
rpcUrl	String	no
grpcUrl	String	no
daemonGrpcUrl	String	no
metadataStatus	String	no
metadataRejectionReason	String	no
registeredAt	BigInt!	yes
blockNumber	BigInt!	yes
transactionHash	String!	yes

vaultProviderStats

Aggregated counters per vault provider.

Query with vaultProviderStats(…) or vaultProviderStatss(…).

Field	Type	Required	Notes
id	String!	yes
activeVaultCount	Int!	yes	Number of active vaults for this provider.
totalActiveSats	BigInt!	yes	Satoshis across the provider's active vaults.
updatedAt	BigInt!	yes
provider	vaultProvider	no

vaultKeeper

An App Keeper: the operator appointed by an integrated application, holding claim and challenge rights under that application's rules.

Query with vaultKeeper(…) or vaultKeepers(…).

Field	Type	Required
id	String!	yes
btcPubKey	String!	yes
firstSeenAt	BigInt!	yes
blockNumber	BigInt!	yes

vaultKeeperApplication

Join between an App Keeper and an application.

Query with vaultKeeperApplication(…) or vaultKeeperApplications(…).

Field	Type	Required
id	String!	yes
vaultKeeper	String!	yes
applicationEntryPoint	String!	yes
version	Int!	yes
registeredAt	BigInt!	yes
blockNumber	BigInt!	yes
vaultKeeperInfo	vaultKeeper	no

universalChallenger

A Universal Challenger: one of a global set of operators with challenge-only rights, which challenges invalid claims across every BTCVault.

Query with universalChallenger(…) or universalChallengers(…).

Field	Type	Required
id	String!	yes
btcPubKey	String!	yes
firstSeenAt	BigInt!	yes
blockNumber	BigInt!	yes

universalChallengerVersion

Versioned challenger set.

Query with universalChallengerVersion(…) or universalChallengerVersions(…).

Field	Type	Required
id	String!	yes
challengerId	String!	yes
version	Int!	yes
blockNumber	BigInt!	yes
challengerInfo	universalChallenger	no

feeConfig

Fee configuration. Empty on testnet — fee escrows exist without a matching config row.

Query with feeConfig(…) or feeConfigs(…).

Field	Type	Required
id	String!	yes
vpFeeRate	BigInt!	yes
ucFeeRate	BigInt!	yes
avkFeeRate	BigInt!	yes
protocolPegInFeeRate	BigInt!	yes
vpRegistrationFee	BigInt!	yes
updatedAt	BigInt!	yes
blockNumber	BigInt!	yes

vaultFeeEscrow

Escrowed fees for one vault. One row per vault, keyed by vaultId.

Query with vaultFeeEscrow(…) or vaultFeeEscrows(…).

Field	Type	Required	Notes
vaultId	String!	yes
totalAmount	BigInt!	yes	Escrowed amount in wei, not satoshis.
vaultProvider	String!	yes
numUniversalChallengers	Int!	yes
numAppVaultKeepers	Int!	yes
status	feeEscrowStatus!	yes
escrowedAt	BigInt!	yes
distributedAt	BigInt	no
refundedAt	BigInt	no
forfeitedAt	BigInt	no
blockNumber	BigInt!	yes
transactionHash	String!	yes
vault	vault	no

feeEscrowStatus values: escrowed · distributed · refunded · forfeited

application

A DeFi protocol integrated with the vault system. Aave v4 is the first.

Query with application(…) or applications(…).

Field	Type	Required	Notes
id	String!	yes
name	String	no
latestVKVersion	Int	no
totalCapBTC	BigInt	no	Satoshis, despite the BTC suffix.
perAddressCapBTC	BigInt	no	Satoshis, despite the BTC suffix.
status	applicationStatus!	yes
registeredAt	BigInt!	yes
blockNumber	BigInt!	yes
transactionHash	String!	yes

applicationStatus values: none · active · paused

token

A token known to the indexer, keyed by contract address.

Query with token(…) or tokens(…).

Field	Type	Required	Notes
address	String!	yes
symbol	String!	yes
name	String!	yes
decimals	Int!	yes	Decimal places for this token. Needed to format any amount denominated in it.

stats

Protocol-wide totals. Singleton, id global.

Query with stats(…) or statss(…).

Field	Type	Required	Notes
id	String!	yes
totalAvailableSats	BigInt!	yes	Satoshis across all available vaults.
availableVaultCount	Int!	yes	Number of vaults currently available.
updatedAt	BigInt!	yes

protocolState

Protocol-level singleton state, such as the active vault-core version.

Query with protocolState(…) or protocolStates(…).

Field	Type	Required
id	String!	yes
activeVaultCoreVersion	Int!	yes
updatedAt	BigInt!	yes
blockNumber	BigInt!	yes
transactionHash	String!	yes

Aave application

State for the Aave v4 integration — the first application built on TBV. A vault used as Aave collateral appears in both domains.

aavePosition

A depositor position in Aave, keyed by depositor address rather than by id.

Query with aavePosition(…) or aavePositions(…).

Field	Type	Required	Notes
depositorAddress	String!	yes	The key for this entity. Query with aavePosition(depositorAddress: "0x…").
proxyContract	String!	yes
totalCollateral	BigInt!	yes	Satoshis. Equals the sum of amount across collateral rows where removedAt is null.
createdAt	BigInt!	yes
updatedAt	BigInt!	yes
blockNumber	BigInt!	yes
transactionHash	String!	yes
collaterals(…)	aavePositionCollateralPage	no

aavePositionCollateral

One vault pledged as collateral against a position. Released rows are kept for history.

Query with aavePositionCollateral(…) or aavePositionCollaterals(…).

Field	Type	Required	Notes
depositorAddress	String!	yes
vaultId	String!	yes
amount	BigInt!	yes
addedAt	BigInt!	yes
removedAt	BigInt	no	Null while the vault is still pledged. Filter on removedAt: null for live collateral.
liquidationIndex	Int!	yes
blockNumber	BigInt!	yes
transactionHash	String!	yes
position	aavePosition	no
vault	vault	no

aaveVaultStatus

Per-vault usage status within Aave, keyed by vaultId.

Query with aaveVaultStatus(…) or aaveVaultStatuss(…).

Field	Type	Required	Notes
vaultId	String!	yes
applicationEntryPoint	String!	yes
status	aaveVaultUsageStatus!	yes	One of collateralized, llp_owned or redeemed.
metadata	JSON	no
updatedAt	BigInt!	yes
vault	vault	no

aaveVaultUsageStatus values: collateralized · llp_owned · redeemed

aaveUserProxy

The proxy contract deployed for a user, keyed by user.

Query with aaveUserProxy(…) or aaveUserProxys(…).

Field	Type	Required
user	String!	yes
proxy	String!	yes
createdAt	BigInt!	yes
blockNumber	BigInt!	yes
transactionHash	String!	yes

aaveReserve

An Aave reserve and its parameters. Join here to resolve debt amounts.

Query with aaveReserve(…) or aaveReserves(…).

Field	Type	Required	Notes
id	BigInt!	yes
underlying	String!	yes
hub	String!	yes
assetId	Int!	yes
decimals	Int!	yes
dynamicConfigKey	BigInt!	yes
paused	Boolean!	yes
frozen	Boolean!	yes
borrowable	Boolean!	yes	Whether the reserve can be borrowed. The vaultBTC reserve, which represents BTCVault collateral, is collateral only.
collateralRisk	Int!	yes
collateralFactor	Int!	yes	Basis points. 7800 is 78%.
createdAt	BigInt!	yes
updatedAt	BigInt!	yes
blockNumber	BigInt!	yes
underlyingToken	token	no	The reserve asset. Read symbol and decimals to format borrow and repay amounts.

aaveConfig

Aave integration configuration. Singleton with an Int id — pass 1, not "1".

Query with aaveConfig(…) or aaveConfigs(…).

Field	Type	Required
id	Int!	yes
adapterAddress	String!	yes
vaultBtcAddress	String!	yes
btcVaultRegistryAddress	String!	yes
btcVaultCoreSpokeAddress	String!	yes
vaultBtcReserveId	BigInt!	yes

Full SDL

The complete schema is committed at /schema/vault-indexer.graphql.

Introspection is available but depth-capped — see Limits and gotchas for the four short queries that reconstruct it.