Beamio Merchant OS
Maturity: Public application. Merchant OS is live at https://biz.beamio.app. This chapter inventories merchant capabilities. It is not an operator runbook and not an audit or SLA claim.
Parent: Beamio whitepaper.
Revision: 2026-08-24.
Product role
Merchant OS is the merchant control plane: create and publish a program card, configure membership and reward rules, issue coupons and catalogs, authorize staff and POS terminals, and review settlements.
It is not the Consumer PWA and not the in-store POS UI. Merchants sign as the owner (or authorized staff) after unlock; signing material stays in session memory and is not written to disk.
What exists today
Programs and metadata
Merchant configuration is written to card0 / metadata_json (HTTP GET https://beamio.app/api/cardMetadata) and, where required, to CoNET program-card modules.
| Area | Behavior |
|---|---|
| Card Setup / Program Basic | Name, imagery, currency, Discover presentation (shareTokenMetadata) |
| Membership | Base membership lives in baseMembership (index 0), not as an Add-tier row. Higher paid tiers live in tiers[] and must be strictly more expensive. After first successful publish, that tier’s price and duration are locked. A successful issue mints a membership NFT with tokenId ∈ [100, 1e11) — leftover #0 program points are not a membership NFT. Fee mode and Add-tier stage read diamond feeE6[], not a misaligned on-card tiers.length. |
| Top-up Promotion | Bonus validity / minimum / percent-or-fixed. The bonus master switch is independent of Reward PT. |
| Reward PT (Top-up) | Actor #13 percent of actual payment (actorPercentBps / chain topupActorRewardRatioE6). Save writes ratio E6 via setTopupActorRewardRatio — not Social Promotion getRewardRule(2). |
| Referrer (Top-up) | Referrer #13 percent (referrerPercentBps / referrerTopupAmountRatioE6) via setReferrerTopupAmountRatio. Same ratio path; not ruleId=2. |
| Social Promotion | Card-level linkClick (ruleId=1) and like (ruleId=3) fixed #13 mint. Coupon-level claim/burn use per-coupon slots. Saving Social Promotion deactivates legacy ruleId=2. |
| Consumption Points | Charge reward percent (chargeRewardRatioE6 / referrer charge ratio). In unified mode, Charge burns #13; the product must not mint token #2 as a spendable balance. |
Trash on Top-up Promotion clears bonus only. It must not clear unifiedRewardPoints.topup.
Unified Reward Points (#13)
User-visible “points / Reward PT” is tokenId = 13.
| Token | Role when unified rewards are on |
|---|---|
#0 |
Redeemable program points (top-up principal and optional promotion bonus #0) |
#13 |
Reward PT / referrer / social rewards (redeemable) |
#1 / #2 |
Statistics only — not spendable rewards |
#3–#30 |
Cumulative / social KPI stats |
Top-up #13 percentages use actual payment only. Promotion bonus #0 is not part of that base.
getRewardRule(2) is not Top-up Reward PT. Historical Social Promotion slot 2 may still exist on old cards as a fixed actorMint13 / refMint13 row. Product truth for Top-up / Referrer Top-up is E6 ratio storage and same-cycle mint (recordTopupCumulativeStat). Master must not enqueue a second #13 mint from slot 2. Social Save must deactivate slot 2 so it cannot dual-mint.
Coupons, catalogs, staff
| Area | Behavior |
|---|---|
| Coupons | Issue, share, open-claim inventory, social stats |
| Business Catalogs | Catalog items, 4:3 preview, optional video / image hero (no item-icon in the editor preview) |
| Staff / Terminals | Linked POS terminals; Pending terminal authorization from typed DePIN Chat (beamio_pos_terminal_permission_v1) — not a Messages thread |
| Messages | Ordinary Merchant OS chat omits mailbox NoPush (offline peer may get a native badge). Delivery receipts use NoPush: true. Same rule as Consumer; see DePIN Chat. |
| Transactions | Indexer ledger. B-Unit service fees are a separate indexer row; the UI merges them into Charge / Top-up / Claim when a parent row exists |
| Overview KPI | Chain-first. A failed RPC must not overwrite the last trusted value with zero |
Fuel and cash (merchant view)
Merchants buy Fuel Packs (B-Units) for protocol fees. Pack merchandising shows price and total B-Units only.
Merchant Kit Stripe (CAD kits → B-Units / Ket) is not the consumer “Buy USDC with card” rail. See Cash and USDC.
Chain placement
Merchant program cards are CoNET L1 only. Do not treat the historical Base UserCard Factory as the current merchant chain.
New cards issued after the CoNET UserCard beacon cutover are BeaconProxy. The platform upgrades every such card together with beacon.upgradeTo; card addresses stay the same. Historical CREATE cards cannot join the beacon and keep the ChargeReward runtime preCheck.
Writes that need sponsored gas go Cluster → Master (CoNET settle pool). Reads of program state, metadata, and KPI should prefer RPC / trusted cache, not a centralized API as the source of truth.
Membership fee modules (CoNET, 2026-08-23)
Existing BeaconProxy cards pick Factory default modules at runtime. Binding the set below repairs fee-mode issue (tokenId ∈ [100, 1e11)) on live cards without a beacon upgrade. The Factory owner must bind AdminStats V6, not the V5 implementation alone (V5 would drop Referrer Registry views).
| Role | Address | Notes |
|---|---|---|
| UserCard Factory | 0xfA52a0CcC96C19cF4b6Ea864615F6d52BD0774FB |
setMembershipStatsModule + setAdminStatsQueryModule |
| MembershipFeeOpsLib | 0xF3Ce015B43012E03706b5d1f57970ebCbB01D5a2 |
Linked into AdminStats V5 |
| MembershipStatsModule | 0x5E0787C8562038F8BA0623274b5bFE68AF5a70E5 |
Issue path; Factory defaultMembershipStatsModule |
| AdminStats V5 (impl) | 0xA439F4E513A241D62687abdBaF37e5Ba61D9889e |
Stage / fee diamond; do not bind Factory here |
| AdminStats V6 (router) | 0xF0d2E8BB78101B7a1dF44B3e8307E8124404419e |
Factory defaultAdminStatsQueryModule; ctor (V5, referrerViews) |
| Referrer views (reuse) | 0x6c7648B1d5339ea844089d2d7c9da72acab2cC9C |
Existing live views; V6 second ctor arg |
Snapshot: deployments/conet-MembershipFeeModules.json. Blockscout: mainnet.conet.network. A leftover #0 from a pre-upgrade empty-tier issue is program points, not a membership NFT. Dirty activeMembershipId in [1, 99] with zero balance is not a valid membership.
Trust boundary
- An unlocked Merchant OS session can sign owner or staff actions until lock / logout.
- Cluster precheck can refuse a write; Master does not re-validate business rules.
- Discover visibility is a published allow policy, not “every card ever created.”
- Staff pending authorization is local-trusted application state plus Chat delivery; it is not automatically an on-chain admin grant until the merchant completes the approval flow.