Nano Settlement Verify

nano-settlement-verify checks a necessary payment condition for a pay-per-call endpoint priced in Nano (XNO). Given a buyer-supplied block hash, an expected amount, and the destination account, it reads the public ledger to determine whether a matching send block is confirmed. The checker holds no seed, signs nothing, sends no funds, and does not implement fulfillment.

Its Python function makes a block_info request to one selected Nano node RPC and performs integer comparisons. A match requires a state block with send subtype, the expected destination in link_as_account, and exactly the quoted raw amount. Receive, open, and change blocks do not qualify even if an amount appears to match. Confirmation requires the node response's confirmed field to equal the string true.

Use it behind an HTTP 402 route priced in XNO, or when a caller presents a Nano block hash and the seller needs to distinguish confirmed payment from a broadcast block. It is a seller-side settlement check rather than a wallet: it cannot send payments or manage keys.

A settled verdict alone never authorizes serving a paid call. A public block hash can be presented by someone other than the payer. The application must bind the payment to the intended order and buyer, then atomically reserve the normalized hash in durable shared storage with a unique constraint. Duplicate hashes, uncertain reservations, and unbound orders must fail closed. A unique quoted amount does not prevent replay, and Nano blocks contain no memo that identifies an order.

The supplied checker is saved as verify.py and called with:

python3 verify.py BLOCK_HASH EXPECT_RAW ACCOUNT [RPC_URL]

BLOCK_HASH must contain 64 hexadecimal characters. EXPECT_RAW is a positive integer string, with one XNO equal to 10^30 raw. Decimal or floating-point input is unsuitable because low digits can be lost; decimals are rejected as invalid_amount. ACCOUNT is the destination account expected to receive payment, rather than the account chain carrying the send block.

The command prints a JSON verdict and returns an exit code. Exit 0 reports settled and returns the uppercase block hash. Exit 2 reports unconfirmed, allowing a later confirmation check. Exit 3 covers mismatches, missing blocks, and invalid inputs. Exit 4 covers an unreachable node or malformed node response; it means verification could not be completed, not that the buyer made a bad payment. Exit 64 indicates incorrect invocation.

None of the non-success outcomes permits fulfillment. An infrastructure failure should be investigated or retried through a trusted RPC rather than treated as either payment success or proof of an invalid payment. Successful verification still proceeds to the application's order binding, replay prevention, and transaction or idempotency handling.

The checker uses the Python 3 standard library and network access to a Nano node RPC, defaulting to https://rpc.nano.to. Its network operation is an HTTPS POST containing the block hash. It does not write files, keep secrets, or change ledger state.

A single node can lag or return incorrect information. For high-value verification, the workflow calls for agreement from two independent RPC URLs. The application remains responsible for durable one-time claims and trustworthy order association; neither is provided by this script.