Enrichment Hints

Mirador enrichment hints connect an OpenTelemetry trace to actions that happen outside your process. Emit a reserved mirador.* event on the active user-flow span, and Mirador follows the action and stitches its outcome into that same trace. Supported actions include EVM, Solana, Canton, Safe, Relay, and Stripe.

The canonical machine-readable contract is published at otel.mirador.org/llms.txt. Use it when generating integrations or prompting a coding agent.

Event catalog

Event name	Tracks	Required identity
`mirador.web3.evm.txhint`	EVM transaction through receipt	`tx.hash` + EVM chain
`mirador.web3.solana.txhint`	Solana transaction	`tx.signature`
`mirador.web3.canton.txhint`	Canton transaction	`tx.update_id`
`mirador.web3.safe.txhint`	Safe multisig confirmation through execution	`safe.tx_hash` + EVM chain
`mirador.web3.safe.msghint`	Safe EIP-712 message signing	`safe.message_hash` + EVM chain
`mirador.web3.relayhint`	Relay bridge deposit through fill	`relay.request_id`
`mirador.stripe.paymenthint`	Stripe PaymentIntent through payout	`stripe.payment_intent_id`

An EVM chain is identified by chain.id, chain.name, or both when they agree.

Attribute reference

Attribute	Type	Required for	Example
`tx.hash`	string	EVM transaction	`0x` + 64 hexadecimal characters
`chain.id`	integer or decimal string	EVM and Safe hints, unless `chain.name` is present	`8453`
`chain.name`	string	EVM and Safe hints, unless `chain.id` is present	`base`
`tx.signature`	string	Solana transaction	Base58 transaction signature
`tx.update_id`	string	Canton transaction	Canton update ID
`canton.party_id`	string	Optional Canton read-as context	`Alice::1220…`
`safe.tx_hash`	string	Safe transaction	SafeTxHash, not the executing transaction hash
`safe.message_hash`	string	Safe message	Safe message hash
`relay.request_id`	string	Relay	Request ID returned by the quote
`stripe.payment_intent_id`	string	Stripe	`pi_…`
`stripe.account_id`	string	Optional Stripe Connect routing	`acct_…`

Extra attributes are preserved as context but do not control tracking.

Attribute keys are literal flat strings. Emit 'tx.hash'; do not send a nested object such as { tx: { hash: value } }.

Emit a hint

Add the event only after the external system returns its identity.

span.addEvent('mirador.web3.evm.txhint', {
  'tx.hash': transactionHash,
  'chain.id': 8453,
  'checkout.step': 'submit',
});

span.addEvent('mirador.stripe.paymenthint', {
  'stripe.payment_intent_id': paymentIntent.id,
  'stripe.account_id': connectedAccountId,
});

span.AddEvent("mirador.web3.evm.txhint", trace.WithAttributes(
    attribute.String("tx.hash", transactionHash),
    attribute.Int64("chain.id", 8453),
    attribute.String("checkout.step", "submit"),
))

span.AddEvent("mirador.stripe.paymenthint", trace.WithAttributes(
    attribute.String("stripe.payment_intent_id", paymentIntentID),
))

span.add_event("mirador.web3.solana.txhint", {
    "tx.signature": signature,
})

span.add_event("mirador.web3.canton.txhint", {
    "tx.update_id": update_id,
    "canton.party_id": party_id,
})

Rules that must hold

Emit an event, not a child span. Add the reserved event to the active user-flow span.
Use the exact event name. Names are case-sensitive.
Emit one event per action. Two transactions require two events; do not use an array of hashes.
Use flat attribute keys. Dots are part of the key name.
Wait for the identity. Do not emit before the transaction, intent, or payment ID is known.
Keep the span sampled. A sampled-out span cannot carry a hint to Mirador.
Flush before exit. Allow the batch exporter to drain or explicitly shut down the provider.

Chain resolution

The EVM and Safe hints accept these forms:

Input	Result
`chain.id: 8453`	Accepted
`chain.id: "8453"`	Accepted
`chain.name: " Base "`	Accepted; normalized and resolved to Base
`chain.id: 1` with `chain.name: "base"`	Invalid because the values contradict
`chain.name: "unknown"` without an ID	Invalid
`chain.id: 0` or `"0x2105"`	Invalid

Known IDs include Ethereum 1, Optimism 10, BNB Smart Chain 56, Polygon 137, HyperEVM 999, Base 8453, and Arbitrum 42161.

Invalid hints are preserved

A reserved event that is missing a required attribute or fails chain validation becomes a normal span event. Mirador preserves it instead of dropping it, but enrichment tracking does not start. This fallback makes typos visible in the trace while preventing Mirador from following the wrong external action.

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

Event catalog

Attribute reference

Emit a hint

Rules that must hold

Chain resolution

Invalid hints are preserved

Next steps

Traces over OTLP

Transaction hints

​Event catalog

​Attribute reference

​Emit a hint

​Rules that must hold

​Chain resolution

​Invalid hints are preserved

​Next steps

Traces over OTLP

Transaction hints

Event catalog

Attribute reference

Emit a hint

Rules that must hold

Chain resolution

Invalid hints are preserved

Next steps