← Blog

The Solana Deeds #5: A stablecoin checkout that reads the chain

A Solana Pay checkout explained as paying an invoice by its reference: a USDC payment from a phone found on chain and checked, a 165,000 lamport fee taken apart, and two library bugs found by paying.

Nissan Dookeran9 min readSolanaCoding AgentsAgent Workflows

You get an invoice. It says: send 12.50 to this account, and quote this invoice number as the reference. You make the transfer, and the reference travels with it.

The shop doesn't take your word that you paid. It looks at its own bank statement, finds your payment by the reference, and then checks the account, the currency and the amount.

That's a stablecoin checkout on Solana. For Deed #5 we built one. A shop asks for 12.50 USDC, the customer scans a QR code with a phone wallet, and the server finds the payment on chain and checks it before it shows a receipt. Deed #4 swapped real money on mainnet. This one is back on devnet, Solana's practice network, so every payment below is test money.

Watch the Deed #5 demo on YouTube.

Where the invoice stops being true

Your bank statement is private. Solana's is public, and anyone can read every transfer on it.

The reference is different too. On an invoice it's a number someone typed. Here the shop makes up a one-off address for each order, and the wallet attaches it to the transfer. To find a payment, the shop asks the network for every transaction that carries that address.

What do you need to know before the QR code?

Four words.

A wallet is an app that holds your key and signs payments for you. A stablecoin is a token that tracks a currency; USDC tracks the US dollar, one for one. Each token you hold sits in its own token account. And SOL, Solana's own coin, pays the network fee, which is counted in lamports. A billion lamports make one SOL.

Lamports come back in a minute.

How does the shop know it was paid?

How a payment is found and checked: the shop's server creates an order for 12.50 USDC with a fresh reference; the checkout page shows a QR code carrying the shop, the amount, the USDC token and the reference; the customer's wallet sends the transfer to Solana devnet with the reference; every 1.5 seconds while the page is open, the server asks devnet for transactions with that reference and checks the account, token and amount; then the page shows paid, with the signature as the receipt.

The server creates an order with a fresh reference. The checkout page shows it as a Solana Pay QR code. Inside the code is a link carrying the shop's address, the amount, the USDC token and the reference.

While the page is open it asks the server every second and a half. The server asks devnet for transactions carrying that reference and checks each one it finds: the recipient, the token, the amount. The first that passes pays the order.

It has to be each one. The Solana Pay library has a helper that returns only the oldest transaction for a reference. With it, a rejected first payment would hide a correct second one.

I paid a 12.50 order from my phone. On that one payment the page turned to paid under 3 seconds after the transfer's block time. The receipt is the transaction's signature, a fingerprint anyone can look up, and it's on Solana's explorer, finalized.

Why was the fee 165,000 lamports and not 5,000?

The basic fee is 5,000 lamports for each signature, and my payment had one. Claude was about to write 5,000 into the video script. The explorer screenshot said ◎0.000165, which is 165,000 lamports.

The other 160,000 was a priority fee my wallet added on its own. When the network is busy, the validators that build the blocks take better-paying transactions first, so wallets add a tip. The wallet sets a price for each unit of computing work and a ceiling on the units, and the tip is one times the other. The transaction's own instructions give both numbers: 800,000 micro-lamports per unit, times a ceiling of 200,000 units, is 160,000 lamports.

It looks big next to 5,000. It's 0.000165 SOL. On devnet that's worth nothing, and if SOL cost $100 it would be under two cents.

It was fine for the wallet to add it. I pay the fee from my own SOL, and the payment is unchanged: the same shop, the same amount, the same reference. I asked for that explanation to get a scene of its own in the video.

What happens when the payment is wrong?

During the first phone test I was offered a second QR code for the same order, in case the first one failed. I approved both. Another 12.50 went to an order that was already paid.

The server had stopped looking at a reference once its order was paid, so the shop was never told. The checkout now keeps counting after an order is paid.

What the customer didWhat the checkout saysHow it was run
Paid 12.50 on a 12.50 orderPaid, with the signatureMy phone, on devnet
Paid 15.00 on a 12.50 orderPaid; 15.00 received; 2.50 to refundA scripted test customer, on devnet
Paid a paid order againStill paid by the first payment; the second is listed to refundA scripted test customer, on devnet
Paid 4.99 on a 5.00 orderUnpaid; 4.99 to refundA scripted test customer, on devnet
Used a wallet that can't payRefused before anything is signed, with the reasonScripted test wallets, on devnet

The last row took a change of design. The first plan had the page check the customer's balance. I pointed out the hole in it: once the QR code hands over to the wallet, a failure that never reaches the chain tells the shop nothing.

Solana Pay has a second kind of QR code, called a transaction request. With it the wallet asks the shop's server for the transaction first, so the server can look at the wallet before anything is signed. A wallet holding no SOL and no USDC is told it may be set to another network. A wallet holding no USDC on a 50.00 order is told 50.00 is missing. Nothing is sent, and the checkout page lists both.

A transaction request needs the server on a public https address, so the plain QR code stays the default.

What did paying it for real break?

Two things in the Solana Pay library.

I paid through a transaction request from my phone. 1.00 USDC moved, and the checkout rejected it. Twice. My wallet, Solflare, had added two fee instructions after the transfer, which the Solana Pay spec allows for a transaction request. The library's validateTransfer reads the last instruction as the transfer. The checkout now drops trailing fee instructions, which move no tokens, before it validates. That's issue #552.

The second showed up when Claude re-read the whole diff before a pull request. For a transaction that failed on chain, validateTransfer throws a TypeError where it should throw a validation error, and our server passed it on. One failed attempt carrying an order's reference would have stopped every later check at that attempt. Two tests reproduced it before the fix. That's issue #551.

Both are reported to solana-foundation/pay with reproductions on devnet, and both are open. On the day this was published, another developer offered to write the fix for #551. No maintainer has replied yet.

The library gave one more problem before any of that. The version on npm, 1.0.26, is from 31 July and is built for @solana/kit 6. The scaffold runs kit 8. The library's source has supported kit 8 since 31 August, as an unreleased 1.2.0. So the checkout uses a build of 1.2.0 made from the upstream commit, and a CI job rebuilds it and fails unless the result is byte for byte the committed file.

Why did the video need three assembled cuts?

I approved the first draft cut, then asked for the scene about the priority fee.

One scene talked about two different refusals, and to me it looked like the same screenshot for both. It was one screenshot: the narration said "this one" twice over a picture that never moved. It now zooms in and outlines each refusal as I say it.

Adding a scene hung the animation script for 29 minutes. Claude waited on it until I asked whether it was stuck.

My first assembled cut still had the synthetic reference voice on the title scene, so it wasn't used. My second was all my voice, but I had reworded five scenes as I read, and the captions still showed the script. A local transcription of the cut found that. The captions now carry what I said.

Then the upload. Claude read the video's address off a screenshot and took two capital I's for lowercase l's, so its first two checks reported the video missing.

I narrated all 15 scenes myself in the voice booth. A synthetic voice read the drafts so I could review the words; it isn't in the published video.

What's still open

Orders live in the server's memory and are lost on a restart. Refunds are listed, not sent. One phone wallet was tested, Solflare. The page turns to paid at confirmed, not finalized.

It runs on my laptop. My phone reached the transaction request through a temporary tunnel. There's no hosted version. The source is public as a snapshot; the build journal and issue history stay private.

A second currency and webhooks, where a provider pushes a notification so the server doesn't have to keep asking, were the stretch goal. They aren't built.

You can check the rest with one command and a devnet keypair holding about 0.05 SOL. pnpm devnet:reproduce makes its own test token and throwaway wallets, runs four cases and reads every result back from devnet. The saved run passed every check in 18 seconds and spent 5,572,120 lamports: rent deposits for four new accounts, plus 40,000 in fees for four transactions with two signatures each.