Version: 0.9.1

Bigmaps

Bigmaps are key-value stores where smart contracts keep large amounts of data. Values in bigmaps are accessed by unique keys. The TzStats bigmap index supports different keys, a hash (script expression hash) and the native typed version of a key. For convenience, both variants are present in responses as hash and key.

Types A bigmap is defined by a key_type and a value_type. While the key type is most often a simple type (int, string, bytes, address, etc) it can also be an object. Values are represented as unfolded (decoded) form and optionally as original Michelson primitives.

Unfolding uses Micheline type annotations from the smart contract to decompose native primitives into nested JSON objects. Annotations become JSON property names. To request the original Micheline primitives, add query parameter prim=1 (bool).

Packed Data When data is packed using the PACK instruction, an unpacked version can be obtained with the unpack=1 (bool) query argument. In this case both key and value contain the unpacked version. We also try to recursively unpack all embedded values of type bytes so that URLs, names and other packed data becomes easier to access.

Metadata Each bigmap entry comes with a set of metadata that describes its latest update time, block hash and height as well as the bigmap id and its owner contract.

Pagination The Bigmap API support paginated queries for keys, values and updates using limit and cursor or offset.

Historic Values To query a bigmap at a certain point in time add the block (int64|hash) query argument. Using block hashes is reorg-aware, i.e. in case you execute a query on a block that becomes orphaned, the API returns a 409 Conflict error.

Use since (int64|hash) argument to query for changes after a block.

Security Warning

danger

Unlike typical on-chain data where values and ranges are predictable the contents of bigmaps is user-controlled and unpredictable. IT MAY CONTAIN MALICIOUS DATA INTENDED TO ATTACK YOUR APPLICATIONS AND USERS! Sanitize data before processing or displaying it.

Bigmap Info

GET /explorer/bigmap/{id}

Returns information about the identity and type of a bigmap. At access native Micheline type info, add prim=1 (boolean)

Schema
Response
Example

Field	Description
`alloc_block` hash	Hash of the block where the bigmap was allocated.
`alloc_height` int64	Height when the bigmap was allocated.
`alloc_time` datetime	Timestamp when the bigmap was allocated.
`bigmap_id` int64	Unique on-chain id of this bigmap.
`contract` hash	Contract that owns the bigmap.
`key_type` object	Typedef describing bigmap keys.
`value_type` object	Typedef describing bigmap values.
`n_keys` int64	Current number of live keys in bigmap.
`n_updates` int64	Total update count.
`update_height` int64	Last update height.
`update_block` hash	Hash of the block containing the latest update.
`update_time` datetime	Last update timestamp.
`delete_height` int64	Height of bigmap deletion (when bigmap was fully removed)
`delete_block` hash	Hash of block containing the deletion.
`delete_time` datetime	Deletion timestamp.
`key_type_prim` object	Native Micheline type for key.
`value_type_prim` object	Native Micheline type for value.

{
  "alloc_block": "BLmmtt7CFJagi9DWTNNjqD1JBBRmknpmcgAcpsJRhw5KQnybBoc",
  "alloc_height": 1365148,
  "alloc_time": "2021-03-01T02:04:41Z",
  "bigmap_id": 523,
  "contract": "KT1Hkg5qeNhfwpKW4fXvq7HGZB9z2EnmCCA9",
  "key_type": {
    "name": "@key",
    "type": "nat"
  },
  "n_keys": 90005,
  "n_updates": 640725,
  "update_block": "BLFiakfUmXoLuN7DGoRkykQjEHr73ShWspXKLEdDC1hwpHiENu6",
  "update_height": 1478163,
  "update_time": "2021-05-19T10:59:14Z",
  "value_type": {
    "args": [
    {
      "name": "issuer",
      "type": "address"
    },
    {
      "name": "objkt_amount",
      "type": "nat"
    },
    {
      "name": "objkt_id",
      "type": "nat"
    },
    {
      "name": "xtz_per_objkt",
      "type": "mutez"
    }
    ],
    "name": "@value",
    "type": "struct"
  }
}

curl https://api.tzpro.io/explorer/bigmap/523

import (
  "context"
  "github.com/trilitech/tzpro-go/tzpro"
)

bigmap, err := tzpro.DefaultClient.Contract.GetBigmap(
  context.Background(),
  523,
  tzpro.NoQuery,
)

Bigmap Values

GET /explorer/bigmap/{id}/values
GET /explorer/bigmap/{id}/{key}

Lists key/value pairs in bigmaps with optional metadata, native primitives and unpacking. The second variant returns a single bigmap value stored at key if exists. Key can be a key hash (script expr hash) or the native key representation (i.e. an address or integer). For pair keys, separate the pair's elements with comma. Supports

paging with limit and cursor / offset
historic key listing using block (int64|hash)
native Micheline primitives prim=1
unpacking of packed data withh unpack=1

Schema
Response
Example

Field	Description
`key` polymorph	The native representation of the key. Integers are bigints wrapped in strings, other types are rendered according to type rules, e.g. addresses, keys and signatures are base58check encoded, timestamps are ISO8601, etc).
`key_hash` hash	The script expression hash for this key.
`value` object	Unfolded and optionally unpacked value, such as simple string or nested JSON objects/arrays to represent records, lists, sets, and maps.
`meta` object	Metadata for the current bigmap entry (optional, use `meta=1`).
`meta.contract` hash	Contract that owns the bigmap.
`meta.bigmap_id` int64	Unique on-chain id of this bigmap.
`meta.time` datetime	Update timestamp for this key/value pair.
`meta.height` int64	Update height for this key/value pair.
`key_prim` object	Native Micheline primitive for key (optional, use `prim=1`).
`value_prim` object	Native Micheline primitive for value (optional, use `prim=1`).

[
  {
    "key": {
      "0": "tz1UBZUkXpKGhYsP5KtzDNqLLchwF4uHrGjw",
      "1": "153"
    },
    "hash": "exprvD1v8DxXvrsCqbx7BA2ZqxYuUk9jXE1QrXuL46i3MWG6o1szUq",
    "key_prim": {
      "args": [
        {
          "bytes": "00005db799bf9b0dc319ba1cf21ab01461a9639043ca"
        },
        {
          "int": "153"
        }
      ],
      "prim": "Pair"
    },
    "meta": {
      "bigmap_id": 511,
      "contract": "KT1RJ6PbjHpwc3M5rw5s2Nbmefwbuwbdxton",
      "height": 1365467,
      "time": "2021-03-01T07:27:27Z"
    },
    "value": "2",
    "value_prim": {
      "int": "2"
    }
  }
  // ...
]

curl https://api.tzpro.io/explorer/bigmap/511/values

import (
  "context"
  "github.com/trilitech/tzpro-go/tzpro"
)

values, err := tzpro.DefaultClient.Contract.ListBigmapValues(
  context.Background(),
  511,
  tzpro.WithMeta().WithPrim().WithUnpack(),
)

// access pair key element
addr, ok := values[0].Key.GetAddress("0")

// access integer value
i, ok := values[0].GetBig("")

Bigmap Updates

GET /explorer/bigmap/{id}/updates
GET /explorer/bigmap/{id}/updates/{key}

List historic updates to a bigmap in chronological order, including keys that have been deleted. The second variant lists updates for a specific key only.Key can be a key hash (script expr hash) or the native key representation (i.e. an address or integer). For pair keys, separate the pair's elements with comma. Supports

paging with limit and cursor / offset
native Micheline primitives prim=1
unpacking of packed data withh unpack=1

Schema
Response
Example

Field	Description
`action` enum	Update kind, one of `alloc`, `update`, `remove`, `copy`.
`bigmap_id` int64	Unique on-chain id of this bigmap.
`key` polymorph	The native representation of the key. Integers are bigints wrapped in strings, other types are rendered according to type rules, e.g. addresses, keys and signatures are base58check encoded, timestamps are ISO8601, etc).
`key_hash` hash	The script expression hash for this key.
`value` object	Unfolded and optionally unpacked value, such as simple string or nested JSON objects/arrays to represent records, lists, sets, and maps.
`meta` object	Metadata for the current bigmap entry (optional, use `meta=1`).
`meta.contract` hash	Contract that owns the bigmap.
`meta.bigmap_id` int64	Unique on-chain id of this bigmap.
`meta.time` datetime	Update timestamp for this key/value pair.
`meta.height` int64	Update height for this key/value pair.
`meta.block` hash	Hash of the block containing the latest update.
`key_prim` object	Native Micheline primitive for key (optional, use `prim=1`).
`value_prim` object	Native Micheline primitive for value (optional, use `prim=1`).
`source_big_map` int64	Source bigmap copied (only for action=copy).
`destination_big_map` int64	Destination bigmap created (only for action=copy).

[
  {
    "action": "update",
    "bigmap_id": 511,
    "key": {
      "0": "tz1UBZUkXpKGhYsP5KtzDNqLLchwF4uHrGjw",
      "1": "152"
    },
    "hash": "expru3VKqrBfsG3ZbP9eBTTpWrYWth5Ypp8qhn6JyM4BR3pTB3PGu8",
    "key_prim": {
      "args": [
        {
          "bytes": "00005db799bf9b0dc319ba1cf21ab01461a9639043ca"
        },
        {
          "int": "152"
        }
      ],
      "prim": "Pair"
    },
    "meta": {
      "bigmap_id": 511,
      "contract": "KT1RJ6PbjHpwc3M5rw5s2Nbmefwbuwbdxton",
      "height": 1365242,
      "time": "2021-03-01T03:39:21Z"
    },
    "value": "1",
    "value_prim": {
      "int": "1"
    }
  }
  // ...
]

curl "https://api.tzpro.io/explorer/bigmap/511/updates?prim=1&meta=1&unpack=1"import (

  "context"
  "github.com/trilitech/tzpro-go/tzpro"
)

upd, err := tzpro.DefaultClient.Contract.ListBigmapUpdates(
  context.Background(),
  511,
  tzpro.WithMeta().WithPrim().WithUnpack(),
)

Bigmaps

Security Warning​

Bigmap Info​

Bigmap Values​

Bigmap Updates​

Security Warning

Bigmap Info

Bigmap Values

Bigmap Updates