`nx_ad_bill.nx` source

1// nx_ad_bill.nx -- LIB: the billing FSM for the "Brought to you by" performance ad engine
2// (ADS-008, CALLOUT-004). NO-WAVE applied to revenue: a charge exists ONLY as a function of a
3// real meter verdict + real, store-resident prices. DEFAULT STATE = NO CHARGE. Reads prices from
4// the SOVEREIGN STORE (adpricing:, ADS-006), never TSV.
5//
6// THE BILL (reads ONLY the meter verdict -- nx_ad_meter ADS-007):
7//   UNMEASURABLE -> REFUSED   (no GREEN meter verdict: cannot bill what we cannot measure)
8//   UNDER        -> $0        (we did not perform -- the default)
9//   PERFORM      -> perform_fee
10//   EXCEED       -> perform_fee + exceed_bonus   (flat fee + ONE flat capped bonus)
11//
12// HARD CEILING: the most a campaign can ever be billed in a period = perform_fee + exceed_bonus
13// (budgetable, never a runaway invoice -- "relationship over a quick buck"). TAMPER/HONESTY:
14// any PENDING price (perform_fee/exceed_bonus = -1, sponsor co-spec ADS-005 not yet set) -> REFUSED.
15// Fail-closed on an unknown verdict. license_tier: ORIGINAL
16import "nx_ad_meter.nx"
17import "nx_ad_store.nx"
18import "nx_syscalls.nx"
19
20const AB_REFUSED: i64 = 0 - 1   // no GREEN meter verdict / unpriceable -> NO CHARGE (the default)
21
22// perform_fee from the store: adpricing:<goal> = goal\tPERFORM_FEE\texceed_mult\texceed_bonus\tccy
23// (field 1). -1 if PENDING/absent.
24func ab_perform_fee_of(price_key: *u8) -> i64 {
25    let pq: *i64 = sys_mmap(16) as *i64
26    let lq: *i64 = sys_mmap(16) as *i64
27    if ads_get(price_key, pq, lq) != 1 { return 0 - 1 }
28    return am_field_int(pq[0] as *u8, lq[0], 1)
29}
30
31// exceed_bonus from the store: adpricing:<goal> field 3. -1 if PENDING/absent.
32func ab_exceed_bonus_of(price_key: *u8) -> i64 {
33    let pq: *i64 = sys_mmap(16) as *i64
34    let lq: *i64 = sys_mmap(16) as *i64
35    if ads_get(price_key, pq, lq) != 1 { return 0 - 1 }
36    return am_field_int(pq[0] as *u8, lq[0], 3)
37}
38
39// THE CHARGE. verdict: AM_UNMEASURABLE(-1) AM_UNDER(0) AM_PERFORM(1) AM_EXCEED(2).
40// Returns the amount, 0 for no-charge, or AB_REFUSED when it cannot be honestly billed.
41func ab_charge(verdict: i64, perform_fee: i64, exceed_bonus: i64) -> i64 {
42    if verdict < 0 { return AB_REFUSED }       // UNMEASURABLE: no GREEN meter verdict -> cannot bill
43    if verdict == 0 { return 0 }               // UNDER: default state, we did not perform -> $0
44    if perform_fee < 0 { return AB_REFUSED }    // price PENDING (sponsor co-spec): cannot price -> refuse
45    if verdict == 1 { return perform_fee }      // PERFORM: flat fee
46    if verdict == 2 {                           // EXCEED: flat fee + ONE flat capped bonus
47        if exceed_bonus < 0 { return AB_REFUSED }
48        return perform_fee + exceed_bonus
49    }
50    return AB_REFUSED                            // unknown verdict -> fail-closed, no charge
51}
52
53// the HARD, budgetable maximum a campaign can be billed in a period; REFUSED if any price PENDING.
54func ab_period_ceiling(perform_fee: i64, exceed_bonus: i64) -> i64 {
55    if perform_fee < 0 { return AB_REFUSED }
56    if exceed_bonus < 0 { return AB_REFUSED }
57    return perform_fee + exceed_bonus
58}
nx_ad_bill.nx source

`nx_ad_bill.nx` source
