Skip to content
sgktasPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

arcpay

USDC invoice payments on Arc, for Telegram bots and other backends.

A merchant should never have to guess which payment belongs to which order. InvoiceRegistry binds an off-chain invoice id to an on-chain payment, so settlement is a contract read instead of a reconciliation heuristic.

Live on Arc Testnet: 0xAa7704CFE6A114f70F185d9fd445aC432856a213 (source verified)

What this gives a merchant

ArcPay is deliberately small: one contract and a TypeScript read-side SDK. It does not custody funds, create wallets, or decide what a payment buys. Your application creates an invoice off chain, asks the payer to call pay(), and uses the contract's recorded balance to decide when to fulfil the order.

It is currently used by the live Acki Nacki Radar Arc testnet trial flow. That integration uses a thin JSON-RPC client compatible with this SDK, then grants a trial only after an authoritative contract-state read. The application layer is responsible for its own user records, expiry, limits, and fulfilment policy.

The problem

Every bot that takes crypto payments rebuilds the same fragile layer. Typical approaches and how they fail:

Approach Failure
Match by exact amount Two buyers of the same plan collide; wallets round; a "unique fractional offset" per invoice is a hack that breaks on rounding
Match by transfer memo Not every transfer path carries one, and the payer can mistype it
Poll the wallet's recent transactions A window of N events plus an outage longer than the window loses a payment silently

All three share one property: a lost payment is invisible. The customer paid and got nothing, and nobody finds out until they complain.

The approach

pay(address merchant, bytes32 invoiceId) payable

The invoice id travels with the payment, in the same transaction, and the contract records it. Nothing to match, nothing to guess.

For a human-readable invoice such as AP-7K3M9Q, the SDK stores the exact uppercase ASCII bytes, right-padded to bytes32; it does not hash the code. The same id is therefore visible in the Paid event and can be decoded again during reconciliation without relying on the merchant database.

  • Invoices cost nothing to create. They are minted off chain in your own database. Most invoices are never paid; charging gas for them would be waste.
  • Payment credits a balance; the merchant withdraws. Forwarding on payment would mean a merchant address that reverts makes the payer's transaction fail — punishing the wrong party.
  • Amounts accumulate. Partial and over-payment work; the merchant applies its own tolerance via isSettled(merchant, invoiceId, expected). A leaked invoice code cannot be redeemed with a dust payment.
  • Two independent read paths. watchPaid is the fast notification; isSettled is contract state and always authoritative. reconcile() replays a block range after downtime. A payment cannot be silently lost.

Usage

import { ArcPay, createInvoice, fromNative, INVOICE_REGISTRY_TESTNET } from "@arcpay/sdk";

const pay = new ArcPay({
  registry: INVOICE_REGISTRY_TESTNET,
  merchant: "0xYourBotWallet",
});

// 1. Mint an invoice — off chain and free.
const invoice = createInvoice("4.00", "AP");   // { code: "AP-7K3M9Q", id, amount }
//    `id` is the readable ASCII code right-padded to bytes32.
//    Show invoice.code to the user; store code + id + amount.

// 2. React to payment.
const unwatch = pay.watchPaid(async (e) => {
  if (await pay.isSettled(e.invoiceId, expectedAmount)) {
    await grantSubscription(e.invoiceId);
  }
});

// 3. After a restart, catch up on anything missed.
for (const e of await pay.reconcile(lastSeenBlock)) {
  // ...
}

Invoice codes use an alphabet with 0/O and 1/I/L removed — people retype these off a phone screen, and those are the pairs they get wrong.

Arc-specific things that will bite you

Found while building this, verified against Arc Testnet on 2026-08-22.

1. USDC has two decimal precisions. The native gas balance (msg.value, getBalance) uses 18 decimals. The USDC ERC-20 interface at 0x3600000000000000000000000000000000000000 uses 6. They are two views of one balance. Mixing them misprices by 10¹². This SDK is 18-decimal native throughout; toNative/fromNative are the only conversion points.

2. eth_newFilter does not work. Arc's RPC answers internal error. viem's watchContractEvent reaches for filters by default over HTTP, so the watcher never fires. Pass poll: true to use eth_getLogs instead.

3. The primary RPC rate limits log polling. Twelve back-to-back eth_getLogs calls, one run each:

Endpoint Succeeded
rpc.blockdaemon.testnet.arc.io 12/12
rpc.drpc.testnet.arc.io 12/12
rpc.quicknode.testnet.arc.io 4/12
rpc.testnet.arc.io (Circle primary) 0/12

Circle's primary endpoint is fine for one-off reads and for sending transactions, but it refuses sustained polling — which is exactly what a payment watcher does. This SDK defaults to a fallback transport across all four, ordered as above, and always attaches an onError handler: a watcher that fails quietly is how payments get lost.

4. Local tests cannot catch any of the above. anvil runs a standard EVM. Every one of these three problems passed 19/19 local tests and only appeared against a real Arc RPC. Run sdk/scripts/e2e.ts against the live chain before believing anything.

Layout

src/InvoiceRegistry.sol     the contract
test/                       19 tests: reentrancy, dust, isolation, fuzz
script/Deploy.s.sol         deployment, key read from .env only
sdk/src/                    TypeScript client
sdk/scripts/e2e.ts          end-to-end proof against live Arc Testnet
sdk/scripts/probe.ts        RPC diagnostic that found problems 2 and 3

Development

forge test                              # contract tests
cd sdk && npm install && npm run build  # SDK
cd sdk && npm run e2e                   # live end-to-end (needs .env, spends testnet gas)

.env holds PRIVATE_KEY and is git-ignored. It is never passed on a command line and never logged.

Status

Arc Testnet only. A mainnet deployment will use separate addresses and must be configured explicitly; testnet payments must never be treated as mainnet payments.

License

MIT

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages