Minting and Provenance

The provenance side of Seedling lives under a domain - a namespace like kingdoms or supply_chain that you choose per URL. A series mints supply-capped, serial-numbered artifacts, and every artifact carries an append-only chain of lineage records where each record's hash covers the previous one - tamper-evident custody without a blockchain.

Series

Creating a series requires a platform admin token; anyone can inspect one:

snug seedling series create --domain kingdoms --name "Sunforged Sword" \
  --max-supply 500 --per-user-limit 1 --allowed-minters any_authenticated \
  --serials sequential --genesis-generator gen_AyXCjwbTZspw@v1
snug seedling series get --domain kingdoms --series-id ser_FucFHewStmQP

--allowed-minters gates who may mint: admin_only (the default), any_authenticated, or service (service identities and admins).
--serials picks sequential or random assignment; artifacts carry serial and a display form like "1 of 500".
--opens-at / --closes-at bound the mint window; minting outside it fails with 409 mint_window_closed (for a future-dated window).
--genesis-generator pins the series to a published generator version, turning mints into generated editions (below).

The series document tracks live counters: minted, retired, and circulating (minted minus retired).

Minting

snug seedling mint --domain kingdoms --series-id ser_FucFHewStmQP \
  --idempotency-key order-7841 --seed glacier-fox-9421

The idempotency key is required and makes minting exactly-once: repeating the call returns the original artifact with "replayed": true instead of consuming supply. When supply runs out the mint fails with 409 supply_exhausted.

On a generator-pinned series a --seed is mandatory (omitting it is 400 invalid_params), and the genesis record embeds a citation - captured live:

"citation": {
  "generator_id": "gen_AyXCjwbTZspw",
  "version": 1,
  "seed": "glacier-fox-9421",
  "params_hash": "sha256:44136fa355b3678a1146ad16f7e8649e...",
  "content_hash": "sha256:b88c5e71e325e73b31ba5b7a8adc196b..."
}

Minting for another principal (--for-id) requires a platform admin token or a service-gated series; otherwise it fails with 403.

Custody records

Records come in five kinds. genesis is written only by mint/track - appending one manually fails with 400 invalid_params. For the rest:

snug seedling records append --domain kingdoms --artifact-id art_vudpHjvMcrFD \
  --kind transfer --to-id usr_bob --ref handshake:deal_1
snug seedling records append --domain kingdoms --artifact-id art_vudpHjvMcrFD \
  --kind retirement

transfer, transformation, and retirement may only be appended by the artifact's current owner, a service identity, or an admin - after a transfer, the previous owner's next attempt fails with 403 (verified with a second user token).
attestation is open to any authenticated caller - third parties can vouch without holding custody.
retirement seals the chain: any later append fails with 409 artifact_retired, and the series' retired/circulating counters update.
--ref service:id attaches an external reference (an escrow deal, an ERP record) to the record.

History and verification

snug seedling history --domain kingdoms --artifact-id art_vudpHjvMcrFD --verify chain

The response contains the artifact, its full record list, and - when --verify is passed - chain_valid (chain mode re-hashes every link and reports the first broken sequence) or additionally genesis_verified (genesis mode re-runs the cited seed triple and compares content hashes). Both returned true live against a four-record chain.

Ownership queries

snug seedling owned --domain kingdoms --principal usr_bob
snug seedling owned --domain kingdoms --principal usr_alice --ever

The default lists current holdings; --ever includes everything the principal ever held, so a transferred-away artifact still appears.

Derivation graph

A transformation record with --input links output to source, and derived walks those edges (depth defaults to 3):

snug seedling records append --domain kingdoms --artifact-id art_dYRCAhZFbcHU \
  --kind transformation --input art_vudpHjvMcrFD
snug seedling derived --domain kingdoms --artifact-id art_vudpHjvMcrFD --depth 3

Note that --input on mint is recorded in the genesis record's inputs but does not create graph edges - only transformation records feed the derived traversal.

Tracking external objects

track places an object that lives in another system under custody without minting from a series - it creates an artifact whose chain root is an attestation-kind record carrying the external reference:

snug seedling track --domain supply_chain --service erp --external-id pallet_8841

The artifact has no series or serial, but supports the full record, history, and ownership machinery above. Tracking on behalf of another principal (--owner-id) requires a platform admin token.

The exact request and response shapes for every endpoint are in the Seedling API reference.