ads2 state

campaigns

// campaignId → compact JSON string

advertiserBal

// g1addr → ugnot balance as string

adViews

// campaignId+":"+g1addr+":"+dayStr → "1" (per-day dedup)

referrals

// advertiserAddr → referrerAddr

refEarnings

// referrerAddr → ugnot earned as string

refPending

// referrerAddr → ugnot pending payout as string

tasks

// taskId → compact JSON string

taskClaims

// taskId+":"+playerAddr → "pending:proofUrl"|"approved"|"rejected"

pendingReview

// campaignId → "1"

admin

paused

init.11

isAdmin

requireAdmin

requireNotPaused

SetPaused

DepositBid

DepositBid credits the caller's advertiser balance with the declared ugnot amount. The caller must attach matching coins to the MsgCall (the VM holds them in the realm's address). The amount is passed explicitly so the realm can credit it without importing chain/banker. Security: the treasury server MUST verify the on-chain balance before approving any campaign spend — it should call AdvertiserBalance() to cross-check the declared amount matches what was actually deposited.

SubmitCampaign

SubmitCampaign stores a campaign JSON and queues it for admin review. Returns the generated campaignId. Status is forced to "pending\_review" regardless of what the client sends.

ReviewCampaign

ReviewCampaign approves or rejects a campaign. Approved campaigns transition to "active" and can receive views.

RecordView

RecordView bills the advertiser one bid\_per\_view for a player watching an ad. Deduplicated per (campaignId, callerAddr, UTC day). Splits 50% of the bid to the referrer if one is registered for the advertiser.

RegisterReferral

RegisterReferral permanently links the calling advertiser to a referrer. Each advertiser may register exactly one referrer; cannot be changed.

ClaimRefEarnings

ClaimRefEarnings moves the caller's accumulated referral earnings into a pending payout queue. The treasury server reads RefPendingClaim(), sends GNOT from the treasury wallet, then calls ClearRefClaim() to zero it.

ClearRefClaim

ClearRefClaim is called by the admin/treasury after disbursing GNOT to a referrer. Zeroes the pending payout entry.

SubmitTaskDef

SubmitTaskDef creates a new paid social task. Returns the taskId.

SubmitTask

SubmitTask records a player's proof-of-completion claim on a paid task.

ApproveTask

ApproveTask marks a task claim as approved. Only the task's advertiser or the admin may approve. Coin reward is handled server-side via the minter.

GetCampaign

GetCampaign returns the JSON string for a single campaign, or "null".

ListCampaigns

ListCampaigns returns a JSON array of campaigns submitted by advertiserAddr.

SelectAd

SelectAd returns the JSON of the winning campaign for the given viewer level, chosen by weighted auction (higher bid\_per\_view = proportionally more weight). Returns "null" if no eligible campaign exists. NOTE: uses time.Now().UnixNano() % totalWeight as deterministic pseudo-random. Not cryptographic — sufficient for ad placement.

AdvertiserBalance

AdvertiserBalance returns the ugnot balance for an advertiser address.

PendingReviews

PendingReviews returns a JSON array of campaigns awaiting admin review.

GetTask

GetTask returns the JSON for a single task, or "null".

ListTasks

ListTasks returns a JSON array of tasks submitted by advertiserAddr.

RefEarnings

RefEarnings returns the claimable referral earnings for an address.

RefPendingClaim

RefPendingClaim returns the pending payout amount for a referrer address. The treasury server calls this before sending GNOT.

TotalViews

TotalViews returns the total recorded view count for a campaign.

GetTaskClaim

GetTaskClaim returns the claim status string for a taskId+claimerAddr pair.

Render

extractField

extractField pulls the value of a simple string or numeric JSON field. Returns "" if the field is absent.

setStatus

setStatus replaces or appends the "status" field in a JSON object.

injectField

injectField sets a string field in a JSON object, replacing an existing value or appending before the closing brace.