Expand description
Fund and read a Knos work order from another Solana program.
knos_pay holds a work order’s money in escrow and pays it when GitHub signs that the order’s terms were met (the token is verified on chain by knos-oidc). This crate is what a program needs to be a FUNDER by CPI: the program ids, the addresses, the three instructions a funder sends (FundOrderWallet, TopUp, RefundOrder) and a reader of the Order account. It depends on solana-program and nothing else, and none of knos_pay’s code.
The funder of an order is whoever signs FundOrderWallet. When that is a PDA of your program (a treasury), your
program signs with invoke_signed; the order then refunds to a token account of that PDA and nowhere else, and
its rent comes back to the PDA. The PDA must be a plain system account (no data): it pays the rent of the order.
use knos_pay_interface as knos;
let f = knos::FundOrder { repo_id, issue, amount, wf_repo: knos::wf_repo_hash("drexthealpha/Knos"), wf_sha, ..Default::default() };
let ix = knos::fund_order_wallet(&knos::ID, treasury.key, treasury_token.key, mint.key, token_program.key, &f, terms_json);
invoke_signed(&ix, &[treasury, order, ov, treasury_token, mint, auth, token_program, system, pause], &[&[b"treasury", &[bump]]])?;
let o = knos::Order::read(order.key, order.owner, &order.try_borrow_data()?, &knos::ID).ok_or(MyError::Order)?;
assert!(o.amount == amount && o.refund_to == *treasury.key);The bytes this crate writes are checked against the Python client’s (src/knos/settle/v2/pay.py) through tests/fixtures/pay_interface.json, which scripts/pay_interface_fixture.py generates; the Order in it is one the test build of knos_pay wrote.
Structs§
- Fund
Order - An order to fund.
amountis what the payees receive (the fee comes on top);work_sis how long the order stays open before it can be refunded;wf_repoandwf_shapin the workflows whose signed run can pay it. A PRIVATE order:optswith F_PRIVATE andsalted,private_scopeset,repo_idandissue0, and thetermspassed tofund_order_walletare the 32-byte terms hash instead of the JSON. - Opts
- What a funder fixes beside the amount and the terms (48 bytes on the wire). Limits: holdback_bps <= 5000 and only with a warranty, warranty_days <= 90, kill_bps <= 2000; a STANDING order has a rate in 1..=amount, any other none.
- Order
- A work order as knos_pay stores it (512 bytes, version 2). An order that was paid out or refunded is gone.
Constants§
- ATA_
PROGRAM - FEE_BPS
- FEE_
OWNER - Fees go to a token account owned by this address. It has no other power.
- F_
FAUCET - F_
NEUTRAL - F_
PRIVATE - F_
STANDING - F_
TOKE N2022 - HELD
- ID
- knos_pay, the second deployment (devnet). Upgradeable only through a multisig with a public 48-hour delay, until an outside review. Every function here takes the program’s id, so another cluster is another argument.
- ID_STR
- MAX_
AMOUNT - MAX_
TERMS - MAX_
WORK - MERGE
- MIN_
WORK - OPEN
- OPTS_
LEN - ORDER_
FEE_ MIN - ORDER_
LEN - ORDER_
MIN_ AMOUNT - TESTS
- TOKEN
- TOKEN_
2022 - USDC_
DEVNET - Circle’s USDC: the only mints the public record counts as real money.
- USDC_
MAINNET - WARRANTY
Functions§
- ata
- The associated token account of
ownerformint(an owner off the curve, a PDA, has one too). - auth
- [“auth”]: owns every token account of the program. Only the program signs for it.
- bps_of
bpsbasis points of an amount, rounded down, without overflow.- fund_
order_ wallet - 15 FundOrderWallet. Accounts: funder(s,w) order(w) ov(w) funder_token(w) mint auth token_program system pause.
Moves amount + order_fee(amount) from
funder_tokento the order’s own token account and creates both; the funder pays their rent and gets it back when the order closes. - order
- [“ord”, scope, source, seq]:
sourceis the funding wallet (or PDA);seqis the funder’s own counter, so one funder can fund an issue more than once. - order_
fee - The fee a funder pays ON TOP of an order’s amount, exactly as knos_pay 2.2 computes it:
bps(FEE_BPS for a wallet’s order) of the amount, rounded down; at least ORDER_FEE_MIN; no maximum and no tiers. FundOrderWallet moves amount + order_fee(amount). - ov
- [“ov”, order]: the token account that holds one order’s money and nothing else.
- pause
- [“pause”]: new funding is refused until the time in it. FundOrderWallet and TopUp take it; it need not exist.
- private_
scope - The scope of a private order: sha256(salt || repo id || issue); the salt stays off chain.
- refund_
order - 22 RefundOrder. Accounts: relayer(s,w) order(w) ov(w) refund_token(w) auth rent_to(w) mint token_program. Anyone sends it and no token is needed: an open order past its deadline (or a held one past its hold) gives everything it holds back to a token account of its funder (default: the funder’s associated token account).
- scope
- The scope of a public order: sha256(“knos3:scope” || repo id || issue).
- terms_
hash - sha256 of the terms JSON: what the order stores and a pay token must carry.
- top_up
- 23 TopUp. Accounts: signer(s,w) order(w) ov(w) from_token(w) balance mint auth token_program pause. Adds
addto an open order’s amount, and the fee on the new amount less the fee already there.signeris the order’s source (the funding wallet or PDA);from_token: a token account of it (default: its associated token account). - units
micromillionths of one whole unit of a mint withdecimalsdecimals, in the mint’s smallest units.- wf_
repo_ hash - sha256 of “owner/name”: the repository that holds the workflows an order pins.