Skip to main content

Crate knos_pay_interface

Crate knos_pay_interface 

Source
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§

FundOrder
An order to fund. amount is what the payees receive (the fee comes on top); work_s is how long the order stays open before it can be refunded; wf_repo and wf_sha pin the workflows whose signed run can pay it. A PRIVATE order: opts with F_PRIVATE and salted, private_scope set, repo_id and issue 0, and the terms passed to fund_order_wallet are 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_TOKEN2022
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 owner for mint (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
bps basis 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_token to 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]: source is the funding wallet (or PDA); seq is 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 add to an open order’s amount, and the fee on the new amount less the fee already there. signer is the order’s source (the funding wallet or PDA); from_token: a token account of it (default: its associated token account).
units
micro millionths of one whole unit of a mint with decimals decimals, in the mint’s smallest units.
wf_repo_hash
sha256 of “owner/name”: the repository that holds the workflows an order pins.