block.ipldsch

# Bitcoin block structure as IPLD Schema
#
# This schema is for illustrative purposes only, Bitcoin encodes using its own
# fixed-format encoding rather than an IPLD DAG format, for which IPLD Schemas
# are intended to describe.
#
# This schema should be read as describing the raw block format with additional
# properties included to show the content-addressing links between the discrete
# entities. These links are prefixed with the `&` link descriptor and are not
# native to the block but are derivable from block data.
#
# See https://specs.ipld.io/schemas/ for details about IPLD Schemas
#

# Header is the first 80 bytes of each Bitcoin block
type Header struct {
  version Int
  previousblockhash Bytes
  parent &Header # previousblockhash converted to CID with `bitcoin-block` codec
  merkleroot Bytes
  tx &TransactionMerkle # merkleroot converted to CID with `bitcoin-tx` codec
  time Int
  bits Int
  nonce Int
}

# TransactionMerkle will either point to other merkle tree nodes, or to
# transactions themselves.
type TransactionMerkle struct {
  leftNode &MaybeTransaction
  rightNode &MaybeTransaction
}

# A faux kinded union, this is not how it works in practice, differentiation
# would occur by checking the length of the bytes, 64-bytes is a
# TransactionMerkle, while > 64-bytes is a Transaction
type MaybeTransaction union {
  | TransactionMerkle bytes
  | Transaction map
} representation kinded

# For SegWit blocks, each transaction will be represented twice as a
# Transaction. The first is from the non-witness version linked via
# txMerkleRoot, none of these instances will contain scriptWitness and the
# segWit field will be implicitly false (it won't be present). The second
# instance will be found by following the txWitnessMerkleRoot from one of the
# TxOuts of the coinbase (first) transaction. The Transactions at the bottom of
# that merkle tree may have scriptWitness data attached.
type Transaction struct {
  version Int
  segwit optional Bool (implicit "false")
  vin [TxIn]
  vout [TxOut]
  scriptwitness optional [Witness] # same number of elements as `vin`
  locktime Int
}

type TxIn struct {
  prevOut OutPoint
  scriptSig Bytes # unbounded vec<char>
  sequence Int
}

type OutPoint struct {
  hash Bytes # 256-bits
  n Int
}

type TxOut struct {
  value Int # int64
  scriptPubKey MaybePubKey # unbounded vec<char>
}

# A faux kinded union, this field is only a WitnessCommitment hash for
# SegWit transactions with one of the coinbase TxOuts where the field starts
# with the bytes [0x6a, 0x24, 0xaa, 0x21, 0xa9, 0xed], the remainder is taken to
# be the txWitnessMerkleRoot. Otherwise the field can be interpreted as a
# scriptPubKey
type MaybePubKey union {
  | ScriptPubKey bytes
  | &WitnessCommitment link
} representation kinded

type ScriptPubKey bytes

type WitnessCommitment struct {
  nonce Bytes # 256-bits, attached to the coinbase TxIn as its scriptWitness
  txWitnessMerkleRoot &TransactionMerkle
}

type Witness bytes # unbounced vec<bytes>