KEEP and the default rule

When a carrier is spent, the artifact has to go somewhere. Three rules decide, in this order.

What you will know after this page

Which rule wins when a KEEP entry and the default rule both point somewhere.
The seven KEEP failure codes: which four void one entry, and which three void the whole marker.
What makes an output eligible at all: not an OP_RETURN, and at or above 10000 sats.
Why a plain payment sends the artifact to the payee at vout 0 instead of to your change.
What to check before you sign a transaction that spends a carrier.

The decision, in order

If a valid KEEP entry names the input that spent this carrier, the artifact follows the vout that entry names.
Otherwise the default rule: the lowest index output that is not an OP_RETURN and holds at least 10000 sats.
If neither yields an eligible output, the artifact becomes a RELIC. That is terminal.

In every case the stretch ends and a ring is engraved. The rules decide where the artifact continues, not whether depth resets. Depth always resets.

KEEP entries

A KEEP marker carries 1 to 8 entries, each two bytes: input_index then vout. The grammar and byte layout are on Marker grammar.

scriptPubKey  11 bytes  6a0950544e410102010002

When an entry is void

Seven conditions, each with its own code. The four KEEP_ENTRY codes void one entry and leave the rest of the marker standing. The other three take the whole marker with them, so every carrier the transaction spends falls to the default rule. None of them destroys an artifact and none of them invalidates the transaction.

Every condition hands the routing back to the default rule. The last column says how much of the marker goes with it.
Condition	Reason code	What is voided
The named input does not spend a carrier	`KEEP_ENTRY_NOT_CARRIER`	That entry
The named vout does not exist in this transaction	`KEEP_ENTRY_OUT_OF_RANGE`	That entry
The named vout is an OP_RETURN	`KEEP_ENTRY_IS_OPRETURN`	That entry
The named vout holds less than 10000 sats	`KEEP_ENTRY_BELOW_MIN`	That entry
Two entries name the same input	`KEEP_DUPLICATE_INPUT`	The whole marker
The marker has no carrier spending input at all	`KEEP_NO_CARRIER_INPUT`	The whole marker
count is zero, above 8, or the payload length does not match count	`KEEP_BAD_GRAMMAR`	The whole marker

Void is not fatal

A void entry does not destroy the artifact and does not invalidate the transaction. It is ignored, and the default rule takes over for that carrier. The invalid event is recorded so you can see what happened, which matters when the default rule sends the artifact somewhere you did not intend.

Entries are per input

One entry routes one input. If a transaction spends three carriers, you need three entries to route all three. Entries that name inputs which are not carriers are void, so you cannot use KEEP to route something that was not there.

One input can name only one vout, which is why a bundle of artifacts sharing a carrier cannot be split by a single transaction. See State machine.

The default rule

successor = first output, in ascending vout order, where
              output is not an OP_RETURN
              and output value >= 10000 sats

Three properties worth being explicit about:

It looks at outputs of the spending transaction only. It never reaches into other transactions.
It does not care who owns the output. An artifact will happily follow money to a stranger.
It is deterministic. Given the transaction, every implementation picks the same output.

Why the default sends artifacts where you did not want

The lowest index output is usually the payment, not the change. If you spend a carrier to pay somebody and take change at vout 1, the artifact goes to the payee at vout 0. This is the most common accidental loss after a plain sweep.

Fix: put a KEEP marker in the transaction, or structure the transaction so the output you want is the lowest eligible one.

The other ways a stretch ends by accident, sweeps and consolidations among them, are collected on the public risks page.

Worked examples

Five spends of the same carrier, differing only in the outputs and the marker. The last column names the rule that decided, which is the part worth carrying away.

Same carrier spend, five different transactions.
Outputs	Marker	Successor	Why
vout 0: 50000 sats vout 1: 120000 sats	none	vout 0	Lowest index at or above 10000
vout 0: 50000 sats vout 1: 120000 sats	KEEP input 0 keeps vout 1	vout 1	Valid entry wins over the default
vout 0: OP_RETURN vout 1: 9000 sats vout 2: 300000 sats	none	vout 2	vout 0 is data, vout 1 is under the minimum
vout 0: 40000 sats vout 1: 9000 sats	KEEP input 0 keeps vout 1	vout 0	Entry void, `KEEP_ENTRY_BELOW_MIN`, default rule applies
vout 0: OP_RETURN vout 1: 4000 sats	none	none	No eligible output. The artifact becomes a relic.

Fees are not an escape hatch

Sats that go to the miner are not an output, so they can never be a successor. A transaction that sends everything to fees leaves the artifact with nowhere to go, and the artifact becomes a relic.

Checklist before spending a carrier

Do you know which artifacts this outpoint carries? Ask POST /patina/safety/outpoints.
Which output do you want the artifact to land on?
Is that output at or above 10000 sats?
Is it the lowest eligible index? If not, add a KEEP entry.
Is there exactly one OP_RETURN starting with PTNA in the transaction?
After it confirms, check the artifact's carrier matches what you intended.