Shared types

A number, an amount of currency, and where a change sits in a store's record. This is its data dictionary at contract v24: one entry for every field of its messages a plugin meets, saying what the field is for, what a value means and does not mean, what empty means, who fills it, its bounds and the operations a write must carry it on. Each entry is anchored by its name, the name a refusal's path resolves to and a declaration names, which never changes.

Its messages are declared in meridian/v1/amounts.proto, meridian/v1/journal.proto. A field's entry is the same whatever carries it: a typed operation's parameters take the entries of the message they are made from.

Decimal

meridian.v1.Decimal, a message.

high

integer · since v2 · stable

Carries the upper half of a number's integer.

• Means: the integer's upper 64 bits, signed: negative for a negative value; the integer is high times 2^64 plus low
• Does not mean: a number on its own: high, low and scale are read together, never apart
• Empty: 0 for a value whose integer fits in the lower 64 bits
• Filled: as-reported
• Unit: none: the upper 64 bits of the value's integer

low

integer · since v2 · stable

Carries the lower half of a number's integer.

• Means: the integer's lower 64 bits, unsigned
• Does not mean: a number on its own, or a signed one
• Empty: 0 is a value: the lower half of an integer that ends in it
• Filled: as-reported
• Unit: none: the lower 64 bits of the value's integer

scale

integer · since v2 · stable

Says how many decimal places the integer carries.

• Means: the places the value was stated with: the value is the integer times 10 to the minus scale, so 1.50 is 150 at scale 2 and stays 1.50; a value of more than 18 places is refused, never rounded
• Does not mean: a precision the platform chose: nothing normalises it, and 1.5 and 1.50 are both kept as stated
• Empty: 0 for a whole number
• Filled: as-reported
• Unit: decimal places
• Bounds: from 0 to 18; past it, refused

Money

meridian.v1.Money, a message.

amount

Decimal · since v2 · stable

Carries an amount of currency.

• Means: the amount in the currency's major unit, whatever the source counted in: an amount read in cents is converted before it is sent
• Does not mean: an amount in minor units, or one without its currency
• Empty: never unset in an amount that is set: the amount is the Money
• Filled: as-reported
• Unit: the currency's major unit
• Bounds: 0 to 18 decimal places; at most 38 significant digits; past it, refused
• Required on: RecordHolding from v2; RecordHoldingsStatement from v2; RecordOpeningBalance from v8; RecordBreak from v8; RecordAccountFigures from v8; ResolveBreak from v8; RecordActivity from v14; RecordPrices from v18; RecordBars from v18; RecordTrades from v19; RecordQuotes from v19; ProposeOrder from v22; RecordOrder from v22; RequestOrderChange from v22; CreatePlacement from v22; RequestPlacementChange from v22; ReportPlacement from v22; ReportExecution from v22; ReportCharge from v22; RecordOutcomes from v23; BookOrder from v24; CorrectBooking from v24; RecordSleeveCross from v24

currency_code

text · since v2 · stable

Names the currency an amount is in, where it has an ISO 4217 code.

• Means: the ISO 4217 code, USD; from v18 a plugin may name a fiat currency by it alone, and core resolves it, dated, to the currency's cash instrument
• Does not mean: a symbol or a currency's name; a pseudo-currency a source reports for an account's base, which a plugin converts to the base's code; a token's code (USDC, USDT), which is refused here
• Empty: never empty on an amount that is set, before v18; from v18 empty for an asset with no ISO 4217 code, which instrument_id alone names
• Filled: as-reported

Changes: v18, clarified: a Money names its cash instrument (decisions/023 as amended): the code is one of that instrument's identifiers, empty for an asset with none, and a token's code is refused.

instrument_id

identifier instrument · since v18 · preview

Names the cash instrument an amount is in.

• Means: the deployment's own ID for the asset's cash instrument, fiat and tokens alike: a USDT amount names USDT's instrument and is never a USD amount; both set must name the same asset, and neither set is refused
• Does not mean: the instrument an amount prices: a price's subject is the row's
• Empty: empty from a plugin that named a fiat currency by currency_code alone, which core resolves; never empty on what core keeps and answers
• Filled: as-reported

JournalRef

meridian.v1.JournalRef, a message.

partition

text · since v7 · stable

Names the partition a change was numbered in.

• Means: the street store's partition, or one of the book's
• Does not mean: an account: one partition numbers many accounts' changes
• Empty: never empty on a change a store numbered
• Filled: decided

sequence

integer · since v7 · stable

Numbers a change in its partition.

• Means: the partition's next number, taken in the change's own transaction, so the numbers have no holes
• Does not mean: a count of one account's changes, or a time
• Empty: never 0 on a change a store numbered
• Filled: decided
• Unit: changes in the partition

previous_sequence

integer · since v7 · stable

Lets a reader of some accounts see a gap in its own.

• Means: the number of the previous change the same row made for the same account
• Does not mean: the partition's previous number, which another account's change may hold
• Empty: 0 for the first change the row made for the account
• Filled: decided
• Unit: changes in the partition

ChangeCause

meridian.v1.ChangeCause, a message.

instance_id

identifier instance · since v7 · stable

Names the plugin instance whose command caused a change.

• Means: the instance that sent the command, as its sidecar stamped it
• Does not mean: the person the command was sent for
• Empty: empty for a change a store made of its own accord
• Filled: decided

acting_for_subject

text · since v7 · stable

Names the person a change was made for.

• Means: the deployment-local subject the command was sent for (W4.9)
• Does not mean: an email address or a display name
• Empty: empty when the plugin acted as itself
• Filled: decided

correlation_id

identifier message · since v7 · stable

Ties a change to the work it was part of.

• Means: the command's correlation identifier, as its envelope carried it
• Does not mean: the change's own identifier
• Empty: empty where the command carried none
• Filled: decided

causation_id

identifier message · since v7 · stable

Names the message that caused a change.

• Means: the command's message identifier
• Does not mean: a message the store published
• Empty: empty for a change a store made of its own accord
• Filled: decided

committed_at_ns

moment · since v7 · stable

Records when a change committed.

• Means: the deployment's clock when the store committed the change
• Does not mean: when the command was sent, or the business date the change stands for
• Empty: never 0
• Filled: decided
• Unit: nanoseconds since the epoch

Watermark

meridian.v1.Watermark, a message.

partitions

repeated message PartitionSequence · since v7 · stable

Names a point in a store's record.

• Means: a sequence per partition: what a read answers it was read at, and what a read of changes since takes
• Does not mean: a time
• Empty: empty for no point at all: a read since an empty watermark reads everything
• Filled: decided

PartitionSequence

meridian.v1.PartitionSequence, a message.

partition

text · since v7 · stable

Names a partition within a watermark.

• Means: a partition of the store that answered
• Does not mean: an account
• Empty: never empty
• Filled: decided

sequence

integer · since v7 · stable

Says how far into a partition a watermark reaches.

• Means: the number of the last change of the partition the point includes
• Does not mean: a count of changes read
• Empty: 0 for a partition nothing has been read from
• Filled: decided
• Unit: changes in the partition

AsReported

meridian.v1.AsReported, a message.

scheme

text · since v11 · stable

Says whose vocabulary a value as reported is in.

• Means: the sending plugin's registry name and, where its source has several code sets, which: plugin:code-set
• Does not mean: an identifier scheme of the instrument store, or anything the platform defines
• Empty: never empty on a value as reported that is sent
• Filled: as-reported
• Bounds: 1 to 64 characters; past it, refused
• Required on: ReportExternalAccounts from v11; ReportMissingInstrument from v11; RecordActivity from v14

code

text · since v11 · stable

Carries the source's code that did not convert.

• Means: the code exactly as the source sent it, for a person to map; sent only beside the field's not-known value
• Does not mean: a value of the contract, or one any reader may act on: nothing past the plugin interprets it
• Empty: never empty on a value as reported that is sent
• Filled: as-reported
• Bounds: 1 to 128 characters; past it, refused
• Required on: ReportExternalAccounts from v11; ReportMissingInstrument from v11; RecordActivity from v14

text

text · since v11 · stable

Carries the source's own words for the code.

• Means: the source's description of the code, as sent
• Does not mean: a translation, or the plugin's own words
• Empty: never empty on a value as reported that is sent: the code again where the source gives no words
• Filled: as-reported
• Bounds: 1 to 256 characters; past it, refused
• Required on: ReportExternalAccounts from v11; ReportMissingInstrument from v11; RecordActivity from v14

RawRecordRef

meridian.v1.RawRecordRef, a message.

instance_id

identifier instance · since v11 · stable

Names the plugin whose storage holds the raw record.

• Means: the instance that wrote the row and keeps the record it was converted from
• Does not mean: a plugin any reader may ask for the record: only the owning plugin's page shows it
• Empty: empty only where no reference is sent; the plugin's SDK sets it, and the sidecar refuses one naming another instance
• Filled: derived, by custody

key

text · since v11 · stable

Names the raw record a row was converted from, in its plugin's own key.

• Means: opaque: the owning plugin's key for a record it keeps as received, which a person follows on that plugin's page; a record the plugin archived resolves to archived, restorable, and one deleted past its window says the record is gone, and the row stands
• Does not mean: a location any other plugin or core may read: no plugin's storage is a channel to another
• Empty: never empty on a reference that is sent
• Filled: as-reported, by custody
• Bounds: 1 to 512 characters; past it, refused
• Required on: RecordHolding from v11; RecordHoldingsStatement from v11; RecordActivity from v14

Changes: v16, clarified: a record the plugin archived resolves to archived, restorable, never to nothing.

Provenance

meridian.v1.Provenance, a message.

field

text · since v11 · stable

Names the value a provenance is for.

• Means: the value's path in its message, as a refusal names a field: quantity, settle_date_quantity, pending, market_value.currency_code, institution
• Does not mean: a field of another message, or of the source's record
• Empty: never empty on a provenance that is sent
• Filled: as-reported, by custody
• Bounds: 1 to 200 characters; past it, refused
• Required on: RecordHolding from v11; RecordHoldingsStatement from v11; RecordActivity from v14

kind

enum ProvenanceKind · since v11 · stable

Says how a value the plugin closed came to be.

• Means: one of four kinds, the same meanings as an instrument value's source, and from v22 a value core computed; a closed value is never presented as the vendor's
• Does not mean: how reliable the value is: a derived value may be exact, and a reported one wrong
• Empty: unspecified is refused
• Filled: as-reported, by custody
• Required on: RecordHolding from v11; RecordHoldingsStatement from v11; RecordActivity from v14

Value	Means
PROVENANCE_KIND_UNSPECIFIED	not said; refused
PROVENANCE_KIND_REPORTED	reported by the vendor, from a raw record other than the message's own
PROVENANCE_KIND_SECOND_SOURCE	from a second source of the plugin's own, never another plugin's storage
PROVENANCE_KIND_SUPPLIED	supplied by a named person on the plugin's page
PROVENANCE_KIND_DERIVED	derived by a named rule in the plugin's code from what the source did send
PROVENANCE_KIND_COMPUTED	computed by core, with its basis (date_basis): a date the date read worked out from the settlement calendars, since it is not the plugin's own rule (W3.20)

Changes: v22, clarified: a fifth kind, a value core computed, with its basis (the calendars spec's Q10).

raw_record

message RawRecordRef · since v11 · stable

References the raw record a reported or second-source value came from.

• Means: the record in the plugin's own storage, where it is not the message's own
• Does not mean: the record a derived value was derived from: the message's own reference says that
• Empty: unset on a value supplied or derived: it never carries a raw record as though the vendor had sent it
• Filled: as-reported, by custody

source

text · since v11 · stable

Names the second source a value came from.

• Means: the source as the plugin names it to a person
• Does not mean: another plugin: a second source is the plugin's own connection
• Empty: empty unless the kind is a second source
• Filled: as-reported, by custody
• Bounds: at most 200 characters; past it, refused

person

text · since v11 · stable

Names the person who supplied a value.

• Means: the person as the plugin's page knew them when they supplied it
• Does not mean: the person a command was sent for, which the envelope says
• Empty: empty unless the kind is supplied
• Filled: as-reported, by custody
• Bounds: at most 200 characters; past it, refused

rule

text · since v11 · stable

Names the rule that derived a value.

• Means: the rule as the plugin documents it, so a person can say what was done: cash net of money market funds the custodian counts in cash
• Does not mean: a rule of the platform's, or one any reader applies
• Empty: empty unless the kind is derived
• Filled: as-reported, by custody
• Bounds: at most 200 characters; past it, refused

date_basis

message DateBasis · since v22 · preview

Says what a date core computed was worked out on (W3.20).

• Means: the rule and each calendar, with their versions, the date read used; never on another kind
• Does not mean: the plugin's own rule, which the derived kind names
• Empty: unset unless the kind is computed
• Filled: derived, by instrument

Backfill

meridian.v1.Backfill, a message.

contract_version

text · since v11 · stable

Names the contract version that added the field a backfill fills.

• Means: v and the version's number, as the version's register names it; the amendment's cause
• Does not mean: the version the plugin was built against
• Empty: never empty on a backfill that is sent
• Filled: as-reported, by custody
• Bounds: 2 to 8 characters; past it, refused
• Required on: RecordHolding from v11

field

text · since v11 · stable

Names the field a backfill fills.

• Means: its path in the message, as a provenance names one; the amendment carries that field and nothing else
• Does not mean: a correction of a value already recorded: a backfill fills only what the row did not carry
• Empty: never empty on a backfill that is sent
• Filled: as-reported, by custody
• Bounds: 1 to 200 characters; past it, refused
• Required on: RecordHolding from v11

---

Generated from boundaries/fields.json in meridian-schema at a6a0af7, contract v24.