Skip to content

Usage

tilttek/bounties

Offering a bounty

A member offers a bounty with a BountyDraft: its identifier, chosen by the application — a ULID, a UUID —, the subject it is offered on, the reason, the amount and the end.

use Phil\Resource\ResourceReference;
use Tilttek\Bounties\BountyDraft;
use Tilttek\Bounties\BountyReason;
use Tilttek\Bounties\Prize;

$bounty = $bounties->offer(new BountyDraft(
    id: '01JD4',
    subject: ResourceReference::of('question', '42'),
    reason: BountyReason::Detail,
    prize: new Prize(100),                      // 100 points; new Prize(5, 'gems') for another unit of points
    endsAt: new DateTimeImmutable('+7 days'),   // required, within the site's rules
), $ana);

The reasons are Attention, Detail, Sources, Reward — an answer given already deserves it —, Creativity and Other. The offer checks the draft against the site's BountyRules — the length, the smallest and largest amount —, checks that the subject has no open bounty and that the sponsor has fewer open bounties than the rules allow — five by default, openPerSponsor —, holds the points out of the sponsor's, keeps the bounty, then dispatches BountyOffered. The same draft sent again by the same sponsor gives back the bounty it offered and holds nothing more; the same identifier with another draft is refused. Points the sponsor does not have throw InsufficientPoints, and nothing is offered.

Claims

$bounties->claim('01JD4', 'answer-901', $bea, 'answer:901');

Any member but the sponsor claims the bounty until it ends: an identifier of the claim, chosen by the application, and an opaque reference to what answers it — an answer, a post, an upload —, of 500 bytes at most without whitespace. A member claims five times at most, and a bounty takes 200 claims.

Limits a member

Each bound keeps one member from flooding the others:

BoundDefaultWhere
Open bounties a sponsor5, from 1 to 100BountyRules::$openPerSponsor
Open bounties a subject1BountyStore::openOn()
Claims a member on one bounty5Bounty::MAX_CLAIMS_PER_MEMBER
Claims on one bounty200Bounty::MAX_CLAIMS
Awards on one bounty20Bounty::MAX_AWARDS
Length of a bounty1 to 30 days, at most 90BountyRules::$shortest, $longest
Amount of a bounty10 to 10,000 points, at most 1,000,000BountyRules::$smallestPrize, $largestPrize

The sponsor's points bound the rest: a bounty is paid in advance. The count of open bounties is read before the offer is kept, so offers of one sponsor sent at the same instant may all pass it; a site that needs the bound exact counts in the same transaction as the offer, in its store.

Awards

$bounties->award('01JD4', 'award-1', 'answer-901', 60, $ana);
$bounties->award('01JD4', 'award-2', 'answer-902', 30, $ana);
$bounties->close('01JD4', $ana);

The sponsor awards points to claims until the grace ends — the end and the grace of the rules, a day by default —: the whole amount to one claim, or shared between several, 20 awards at most, never more than what is left. Each award has an identifier: sent again, it changes nothing. Once the whole amount is awarded, the bounty is settled at once.

How a bounty is settled

MoveByWhenThe points
The whole amount awardedThe sponsorBefore the grace endsPaid to the winners
close()The sponsorWith at least one award, before the grace endsThe awards paid, the rest given back
cancel()The sponsorBefore any claimGiven back
expire(), expireDue()A scheduled taskOnce the grace is overThe awards paid and the rest given back; everything given back when nothing was awarded
open ──► awarded
  └───► expired | cancelled

A bounty with claims is not cancelled: it is awarded, or it expires. The awards to one member are paid together, in one payout. A settled bounty never changes again, and its subject is free for a new bounty. Each settlement dispatches one BountyAwarded for each winner and one BountyClosed, after its escrow move.

Reading a bounty

get($id) gives the Bounty: its state, claims and awards, awarded() and payouts(). Bounty::toArray() gives the record an application keeps, and Bounty::fromArray() reads it back, checked field by field and as a whole: a record no move could have written is refused with InvalidBounty.

Times

Every time is kept in UTC to the microsecond, whatever the time zone of the clock or of the draft. The library orders times with < and >=, and compares two times only by what they write, never with == or ===.