The technicals

This page documents FDRE completely: the product, the money, the protocol, the failure modes and the code that runs it. It is written to be enough to rebuild the whole thing from scratch without ever seeing the repository. If something here is vague, that's a bug — say so.

Why a shelter and not a marketplace

Every NFT venue ever built is a store. Stores are organised around price: listings, floors, bids, royalties, rank. That machinery is useful when something is worth money. It is actively harmful when something is worth nothing, because a store has no way to express “worth nothing, still worth keeping.” The listing sits at 1 DOGE forever, nobody browses page nine, and the asset dies of neglect in a wallet.

A shelter is organised around a different question: who wants this? Remove price and you remove the entire apparatus — no order book, no escrowed bids, no royalty splits, no fee tiers, no marketplace account. What's left is almost embarrassingly small: a list of things, and a button that says take one.

The consequences are practical, not sentimental:

• Newest first, always. There is no ranking algorithm to game because there is no ranking. Arrival order is the only order.
• No listing decisions. The shelter can't curate what it's given. If it's an inscription and it arrives, it's a resident.
• No custody argument. Nobody is trusting the shelter with something valuable. The whole premise is that it wasn't.
• The fee can be honest. With no listings and no valuations to protect, there is nothing to inflate: the price is the transfer's cost plus a small fixed margin, written down to the koinu on this page.

Doginals and DRC-20, briefly

If you already know how ordinals work on Dogecoin, skip to the life of a resident.

A Doginal (a Dogecoin ordinal, or inscription) is arbitrary data — an image, some text, a JSON blob — written directly into the Dogecoin blockchain and bound to one specific unspent output. There is no contract, no token standard and no external server. The data is the chain. Owning the Doginal means holding the private key that can spend that one particular coin, and moving the Doginal means spending that coin to somebody else.

Mechanically an inscription is written with a commit/reveal pair: the first transaction commits to a script hash, and the second spends it, revealing the script — and with it the payload — into the chain forever. The resulting output usually carries a tiny amount of DOGE (postage, around 0.001 – 0.01 DOGE). That postage is not the value; it's the vehicle.

DRC-20 is a token convention built on top of inscriptions. Balances are not held in a contract; they are computed by indexers reading inscribed JSON of the form {"p":"drc-20","op":"transfer","tick":"...","amt":"..."}. Sending tokens is a two-step dance: first you inscribe a transfer inscription (a parcel of a given size), then you send that parcel's coin to the recipient. FDRE holds and rehomes the parcels — a resident tagged DRC-20 is an unspent, unlisted transfer inscription sitting at the shelter, ready to be handed over intact.

The single most important consequence: a Doginal is a coin. If a careless wallet ever spends that coin to pay a network fee, the inscription is gone — not transferred, not burned on purpose, just paid to a miner as sats. This is the number-one way people lose ordinals, and it is why the safety model below is built the way it is.

The life of a resident

A resident is identified by an outpoint — txid:vout, the exact coin carrying the asset — because that is what the asset actually is. Not a token ID, not a database row. A coin.

Intake is a read-only sweep that runs about once a minute. It asks the indexer what inscriptions and unspent DRC-20 transfer parcels the shelter address currently holds, and reconciles that against the ledger. Anything new gets the next sequence number and an arrived timestamp. Anything that vanished without an adoption is marked departed.

The sweep is fail-closed in the direction that matters: if the asset indexer can't answer, it changes nothing at all. A single bad minute at the indexer must never empty the yard, because arrived is stamped once and never rewritten — it is every resident's place in line, and it is not recoverable if thrown away.

The adoption fee, exactly

Here is the whole calculation, with no rounding hidden anywhere. All amounts are integer koinu (1 DOGE = 100,000,000 koinu); on-chain money is never floating point.

vbytes   = 148 × 3 inputs + 34 × 2 outputs + 10   = 522
transfer = ceil(vbytes × fee_rate / 1000)
due      = max(1 DOGE, ceil(transfer × 1.5))

Three inputs and two outputs is the shape of a real transfer: the asset's own coin, one or two plain coins to pay the fee, an output carrying the asset to you and one carrying change back to the shelter. The engine's fee floor is 0.20 DOGE per kilobyte, so a transfer costs roughly 0.10 DOGE, times 1.5 is 0.16 DOGE — under the floor. In practice you pay 1 DOGE.

So why carry the multiplier at all? Because a fee floor is a promise about today's network. If Dogecoin ever gets busy enough that a transfer costs more than about 0.67 DOGE, the multiplier takes over and the shelter still never adopts out at a loss. The floor keeps it simple now; the multiplier keeps it solvent later.

Where your DOGE actually goes. Your payment is swept into the shelter. The miners take the transfer's real cost — at the 0.20 DOGE/kB fee floor that is about 0.10 DOGE for a 522-byte transfer. So an adoption brings in 1 DOGE and spends roughly a tenth of it, and the shelter keeps about 0.9 DOGE. That balance is doing two jobs at once: it is the float that pays the next adopter's network fee before their money arrives, and it is the shelter's margin.

That is the entire business model, stated plainly because a shelter that is coy about its money is not a shelter. There is no commission on what a Doginal might be worth, no listing fee, no royalty, no token and nothing to buy. If the margin ever needs to change, it will change on this page first.

The ten-minute hold and the stable queue

When you claim a resident, three things happen at once, under one lock: the resident is marked held with a deadline ten minutes out, a brand-new single-use deposit wallet is generated, and its private key is written to an encrypted vault. Two people clicking the same face in the same second cannot both walk out with it — the ledger is serialised.

Every claim gets its own deposit address. That is not paranoia, it's arithmetic: with one shared address and a 1 DOGE price, two simultaneous adopters are indistinguishable. A fresh address per claim makes “did this person pay?” a question with exactly one answer.

If the funding doesn't arrive in ten minutes the hold lapses and the resident returns to the floor. Critically, it returns to the same place in the queue. The ledger never rewrites arrived, and the site sorts by arrived, so a claim that goes nowhere is invisible in the ordering — as if it never happened. A resident that has been passed over keeps a quiet counter, which is the only trace.

One deliberate exception: if the chain can't be read, the hold extends rather than lapsing. An unreadable chain is not evidence that nobody paid, and releasing a resident somebody has already funded is the single worst thing this system could do. Outages postpone; they don't decide.

Architecture

FDRE is deliberately small. There is no framework, no build step, no database server, no container, no queue, no CDN and no client-side router.

The design rule the whole platform follows: the money engine is a vessel, the project is a passenger. FDRE owns its policy — the queue, the hold, the fee, the site. It owns none of the money machinery. Key handling, coin selection, signing and broadcasting exist in exactly one place, are audited in exactly one place, and are shared by every project on the box. A bug fixed there is fixed everywhere; a bug introduced there is caught by everyone.

The safety model

The shelter's wallet is full of other people's inscriptions. Every protection below exists because the failure it prevents is irreversible.

1. Fail-closed coin classification

Before any transaction is built, every coin at the shelter is classified against the chain's authoritative unspent-output set overlaid with the asset indexer's view: cardinal (proven to carry nothing, safe to spend on fees), inscription, drc20, dune, or unknown. A coin is called cardinal only when it can be affirmatively proven clean — the indexer answered, the outpoint is not a known asset, the value is above the dust band where inscriptions hide, and the creating transaction carries no metaprotocol marker. Anything unproven is unknown and is never spent.

If the indexer is unreachable, nothing is spendable and the adoption simply waits. A held-back clean coin costs a few minutes. A burnt inscription is forever.

2. The asset coin is never a fee

A transfer pins the asset's coin as input zero and pays its exact value to the adopter as output zero. Network fees come only from separately selected cardinal coins. Before broadcast, the signed transaction is decoded by a full node and asserted: output zero pays the adopter, and carries the asset's exact value. If either check fails, nothing is sent.

3. The operator gate

Broadcasting is refused unless two independent switches are both on: a flag file on disk, and an environment variable on the running process. The service ships with neither. In that default state FDRE does everything except touch the network — it takes in residents, quotes, holds, watches deposits, builds and signs transactions, and stops. Turning it live is a deliberate, auditable operator act, not a deploy artifact.

4. Crash-safe, once-only broadcasting

A signed transaction is written to the claim record before the first broadcast attempt, and any retry re-broadcasts those exact bytes rather than rebuilding. Rebuilding after a partial broadcast is how a system ships the same asset twice. On resume: if the transaction is already on-chain, skip; if its intended inputs were provably spent by something else, halt for a human. An RPC that merely can't answer is a wait, never a verdict.

5. Keys

The shelter's key and every single-use deposit key live in an age-encrypted vault. A key reaches the signer on standard input, is used, and the reference is nulled. No key is ever printed, logged, echoed into an error message, or returned by any HTTP route. Error objects that could embed a command line containing a key are caught and replaced before they can surface.

The one deliberate risk

An adoption starts the moment the funding appears on the chain, not when it confirms. That is a choice, and it is the only place FDRE knowingly accepts a loss.

Waiting for a confirmation would mean waiting about a minute on average and sometimes much longer, turning a cheerful click into a progress bar. Accepting a zero-confirmation sighting makes adoption feel instant. The exposure if someone deliberately double-spends their own 1 DOGE payment is: one adoption's fee, and one resident that goes home for free. The shelter's coffee can absorbs it, and honestly, the pet still got a home.

It is written down here rather than buried because a system that hides its accepted risks is lying about the ones it hasn't found.

The public API

Everything the site knows is readable without a key, an account or a rate limit worth mentioning. Build on it.

There is exactly one write endpoint, POST /api/claim, which takes an outpoint and a destination address and returns a deposit address. It moves no money and signs nothing.

How this page is built (and why it's fast)

Worth documenting because it is unfashionable and it works. This site is rendered to static HTML on the server and written to disk. Every page — including the yard, which changes as residents arrive — exists as a complete file before anyone asks for it. There is no client-side data fetch on first paint, no hydration, no loading skeleton and no JavaScript requirement for any content whatsoever.

What that buys:

• Crawlers see everything. Not every crawler executes JavaScript, and those that do execute it late and on a budget. A file on disk has no such problem.
• Language models see everything. Most retrieval pipelines fetch raw HTML. A single-page app returns them an empty <div>.
• Every resident has a real URL with its own title, description, preview image and structured data — an actual page, not a fragment behind a hash route.
• It's quick. One document, one stylesheet, no framework, no fonts to fetch, no third-party script anywhere on the page. Nothing on this site contacts any host but this one.

JavaScript is used for exactly two things, both after the content is already readable: the adoption dialog, and a quiet poll that keeps countdowns honest. Turn it off and you can still read every word, see every resident and follow every link.

Open source

FDRE is small on purpose so it can be copied. The specification above is complete: intake, the ledger, the queue invariant, the fee arithmetic, the hold, the safety model and the API. Anyone can build a compatible shelter on any chain that has an ordinal-like construct.

The reference implementation is MIT licensed — roughly a thousand lines of standard-library Python plus a static renderer, sitting on a shared Dogecoin engine that is itself dependency-free. It runs comfortably on one small server alongside everything else.

If you want to run a shelter, the parts you must get right, in order of how badly they bite:

1. Never spend an asset coin as a fee. Classify fail-closed, refuse to guess, and halt when the indexer is down.
2. Sign offline, broadcast through one choke point, and gate that choke point behind a switch a human has to flip.
3. Persist the signed transaction before broadcasting it, and never rebuild on resume.
4. Stamp the arrival time once, and never let any other code path write it.
5. Treat an unreadable chain as a wait, not an answer.

Glossary

Cardinal coin

An unspent output proven to carry no inscription, token or metaprotocol data — the only kind of coin that may be spent to pay a network fee.

Doginal

A Dogecoin ordinal: data inscribed directly into the blockchain and bound to one specific unspent output.

DRC-20

A token convention on Dogecoin where balances are derived by indexers from inscribed JSON rather than held in a contract.

Dune / dunestone

A separate Dogecoin metaprotocol that rides on ordinary-looking outputs, marked by data in the creating transaction. Detected and protected, never spent.

Koinu

The smallest unit of DOGE; one hundred-millionth. All on-chain arithmetic here is integer koinu.

Outpoint

A txid:vout pair identifying one specific coin. A resident's true identity.

Postage

The small amount of DOGE carried by an inscription's output. It travels with the asset and is not part of the adoption fee.

Transfer inscription

A DRC-20 parcel: an inscription declaring an amount, which is spent to a recipient to move that balance.