ord 0.27.1

◉ Ordinal wallet and block explorer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

Properties
==========

Inscriptions may include [CBOR](https://cbor.io/) properties, stored as data
pushes in fields with tag `17`. Since data pushes are limited to 520 bytes,
CBOR longer than 520 bytes must be split into multiple tag `17` fields which
are then concatenated before decoding.

Properties are a structured counterpart to [metadata](metadata.md). While
metadata may contain arbitrary CBOR which has no protocol-defined meaning, and
is presented on `/inscription` as free-form HTML, properties have
protocol-defined meaning and must conform to a strict schema.

Indefinite-length CBOR types are not supported in properties. All maps, arrays,
byte strings, and text strings must be definite.

The non-normative [CDDL](https://datatracker.ietf.org/doc/html/rfc8610) schema
of the properties value is as follows:

```cddl
Properties = {
  ? 0: [*Item],
  ? 1: Attributes,
  ? 2: bytes, ; concatenated gallery item transaction IDs
  * any => any,
}

Item = {
  ? 0: bytes .size (32..36),
  ? 1: Attributes,
  ? 2: uint, ; inscription ID index
  * any => any,
}

Attributes = {
  ? 0: text,   ; title
  ? 1: Traits, ; traits
  * any => any,
}

Traits = {
  ; trait names must be unique
  text => Trait,
}

Trait = bool / int / null / text;
```

The above CDDL schema is provided as a convenience. As always, the ordinals
reference implementation `ord` is the normative specification of inscriptions,
and thus the properties field.

Fields matching the `* any => any` wildcard must be accepted but ignored, for
compatibility with future additions.

Compression
-----------

If the inscription property encoding field, tag 19, is set to "br", the value
of the properties field will be decompressed with
[Brotli](https://en.wikipedia.org/wiki/Brotli).

Inscription properties my be compressed when inscribing with
`ord wallet inscribe` and `ord wallet batch` with the `--compress` flag.

To avoid decompression bombs, the maximum size of decompressed properties is
4,000,000 bytes.

To avoid denial-of-service attacks, the maximum compression ratio of
decompressed properties is 30:1. So, for example, if the compressed properties
are 100 bytes, the maximum size of the decompressed properties is 3,000 bytes.

Inscriptions with any of the below issues are treated by `ord` as if they have
no properties:

- properties encoding field set to a value other than "br"
- properties which decompress to over 4,000,000 bytes
- properties with a compression ratio greater than 30:1

Galleries
---------

Inscriptions whose properties field contains `Item`s are galleries.

Galleries contain `Item`s, whose key `0` contains a serialized inscription ID.
Inscription ID `TXIDiINDEX` is serialized as a byte string containing the 32
byte `TXID`, concatenated with by the four-byte little-endian `INDEX`. Trailing
zeros may be removed from four-byte `INDEX`, so IDs ending in `i0` may be
serialized in 32 bytes.

Gallery items are displayed on the inscriptions `/inscription` page on the
explorer.

Galleries are similar to children, in that they provide a way to create
collections of inscriptions. However, galleries are permissionless. Anyone may
create a gallery including any inscriptions. Thus, inclusion in a gallery does
not imply provenance. Additionally, because of this, inclusion in a gallery
does not create a backlink from the gallery item's `/inscription` page to the
gallery.

Galleries may be created when batch inscribing with `ord wallet batch` by
including an array of string inscription IDs of under the `gallery` key of the
inscription entry in the batch file, or when using `ord wallet inscribe` using
the `--gallery` option.

### Item Inscription IDs

Inscription IDs consist of a 32-byte bitcoin transaction ID and an 0-4 byte
integer index, defaulting to zero if omitted. Transaction IDs are effectively
incompressible, since they are as-if-random cryptographic hash digests.

Interleaving this incompressible data with the rest of the properties CBOR can
reduce the compressibility of the entire properties CBOR object.

In order to allow for better compressibility, an alternate encoding of gallery
item inscription IDs is allowed. Both schemes are interchangeable and must be
accepted and displayed identically.

The inline encoding is described above, where each gallery item's 32 to 36 byte
inscription ID is stored under `Item` key `0`.

The packed encoding stores the concatenated 32-byte transaction IDs of all
inscription IDs under `Properties` key `2`, with the indices stored as integers
under `Item` key `2`. Omitted indices default to the value `0`.

Attributes
----------

Attributes are structured metadata that may be attached to both inscriptions
and gallery items.

### Traits

Traits are a structured counterpart to metadata. While metadata may be
arbitrary CBOR, traits are ordered maps of string names to values. Names must
be unique, and values may be booleans, integers, `null`, or strings.