Skip to content

tilttek/bounties

✅ published

Playful bounties prepaid in points, held in escrow, claimed and awarded within a bounded time; never money.

Ana wants a better answer to her rules question and offers a bounty of 100 points, open for a week. The points leave her balance at once and are held. Bea and Cy answer and claim it; Ana awards 60 points to Bea's answer and 30 to Cy's, then closes the bounty: Bea receives 60, Cy 30, and the 10 left go back to Ana. Had Ana awarded nothing by the end of the grace that follows the week, every point would have gone back to her; had she awarded something and forgotten to close, the awards would have been paid then, the rest given back.

A bounty is offered on a subject — a question, a quest, a request —, one open bounty at a time on each, with a reason chosen from a list. Its length is bounded and required. Each bounty is an explicit state machine; every move is checked, kept only if no other writer kept another first, then settled in the escrow and announced by an event. A move sent again changes nothing. Every time is in UTC.

It is a plain PHP library. The application keeps the bounties and the points in its own storage, through two ports; the library ships a memory implementation of each, and an escrow on the ledger of tilttek/points. A bounty is points, never money: the library has no field and no adapter for money.

Status

PartState
Bounties: offer, claim, award, close, cancel, expire, settle, erase, with a limit of open bounties a sponsorImplemented and tested
Bounty: the state machine, its limits, and its record written and read back, checkedImplemented and tested
Contract\BountyEscrow, with Escrow\InMemoryBountyEscrow and Escrow\PointsBountyEscrow on tilttek/pointsImplemented and tested
Contract\BountyStore, with Store\InMemoryBountyStoreImplemented and tested
Event\BountyAwarded and the other events, dispatched through PSR-14Implemented and tested
Exceptions under one BountiesException interfaceImplemented and tested

Documentation

DocumentWhat it covers
InstallationRequirements, installing and wiring.
UsageOffering a bounty, claims, awards and how a bounty is settled.
EscrowHow the points are held, paid and given back, and an escrow on tilttek/exchange-bundle.
PrivacyErasing a member: leaving each bounty, then a pseudonym in their place.
CelebrationsAnnouncing a bounty awarded, with the celebration of the PHIL UX kit.
Extension pointsThe ports, writing a store, and the events.
TestingThe library's tests, fuzz targets and benchmarks.
ReferenceEvery type of the library, with its role, and its exceptions.

Quick start

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

$bounties = new Bounties($store, $escrow, $eventDispatcher);

$bounties->offer(new BountyDraft('01JD4', ResourceReference::of('question', '42'), BountyReason::Detail, new Prize(100), new DateTimeImmutable('+7 days')), $ana);
$bounties->claim('01JD4', 'answer-901', $bea, 'answer:901');
$bounties->award('01JD4', 'award-1', 'answer-901', 100, $ana);   // the whole amount: Bea receives 100 points at once

Requirements

PHP 8.5 or later with sodium, phil/resource 0.1, tilttek/points 0.1 or 0.2, psr/clock, psr/event-dispatcher and symfony/clock.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

License

MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Tilttek project. See LICENSE.