Skip to main content

Grants operations

This guide documents business semantics across programs, assignments, grants, and campaigns.

Object responsibilities​

  • Program defines issuance policy template.
  • Assignment binds template to account/source context.
  • Grant is the consumable lot with lifecycle and balances.
  • Campaign orchestrates bulk issuance windows and targeting.

JSON contracts you should standardize​

Program eligibility payload​

grant_programs.eligibility_payload is consumed with eligibility_kind.

  • For eligibility_kind=subscription_group, supported targeting keys are:
    • subscription_group_id
    • group_key

Public grant bindings​

Plan, catalog, and campaign bindings all use exact {grant_program_code, amount_xusd} objects. Both fields are required, a program may appear only once in one source, and no structural override or binding metadata is accepted.

Keep cadence, anchor, window, kind, priority, ledger, and outstanding-balance behavior in the grant program. Create another program when a flow needs different mechanics.

Manual assignment creation likewise accepts a required top-level amount_xusd; public metadata is annotations only. Vluna may carry the validated amount through private assignment metadata internally, but grant_override and grants are reserved implementation keys and are not public configuration surfaces.

Critical invariants​

  • Cross-account operations are scope-gated; account mismatch is blocked unless elevated access allows it.
  • Manual grant and program grant are distinct issuance modes with different validation rules.
  • Grant consumption entries are derived from allocation facts, not independent write streams.
  • Campaign deletion is conditional (hard delete vs soft-close) based on assignment references.
  • Compensation use-case: manual issuance with strict idempotency discipline.
  • Productized credit use-case: program mode with explicit program governance.
  • Large rollout use-case: campaign orchestration + assignment linkage + post-run closeout.

Audit and control guidance​

  • Always capture operator intent (reason, ticket, source reference).
  • Prefer compensating grants/closures over destructive mutation.
  • Keep grant state transitions explicit (issuance_status, closure_kind) and reviewable.

High-risk mistakes​

  • Using program mode with non-one-time manual-eligibility programs.
  • Treating consumption entries as mutable ledger.
  • Deleting active campaigns without checking assignment linkage.

Next​