Studio Operators
What a studio's operators use to give their players credits out of the studio's budget
Requires signed fetch. Answers every studio the signing wallet is an operator of (an empty list for a wallet that is not one), with what its operators see of it, and the ceiling for a single grant.
Signed fetch authentication using @dcl/platform-crypto-middleware (ADR-44l). Requires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation. See http://adr.decentraland.org/adr/ADR-44l for details.
The wallet's studios
The request is not signed, or its signature is invalid
Internal server error
GET /operator/studios HTTP/1.1
Host: credits.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"studios": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"status": "active",
"balanceCents": 1,
"grantedCents": 1,
"grantCount": 1
}
],
"grantLimits": {
"maxGrantCents": null
}
}One of the signing wallet's studios, with its grants (studio operator)
Requires signed fetch from a wallet that acts for the studio; any other wallet is answered 404. Answers the studio, a page of its grants (newest first) and the ceiling for a single grant. Deposits and adjustments, and who made them, are not shown to operators.
Signed fetch authentication using @dcl/platform-crypto-middleware (ADR-44l). Requires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation. See http://adr.decentraland.org/adr/ADR-44l for details.
500The studio and its grants
Invalid studio id or request body
STUDIO_NOT_FOUND: no studio with that id, or the signing wallet does not act for it
Internal server error
GET /operator/studios/{studioId} HTTP/1.1
Host: credits.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"studio": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"status": "active",
"balanceCents": 1,
"grantedCents": 1,
"grantCount": 1
},
"grants": [
{
"creditId": "text",
"recipient": "text",
"usdCents": 1,
"reason": null,
"grantedBy": "text",
"createdAt": 1
}
],
"page": {
"limit": 1,
"offset": 1,
"total": 1
},
"grantLimits": {
"maxGrantCents": null
}
}A studio operator gives a player Shop credits (1 credit = 10 cents) out of the studio's budget. Requires signed fetch from a wallet that acts for the studio; that wallet is recorded as the granter. A wallet that does not is answered 404, as if the studio did not exist, and that is checked before anything else, a past grant included. Whether it still acts for the studio is checked again where the grant is written.
The credits do not expire and are written with credit_source = studio_grant: they appear in GET /credits like any grant (its default listing, with no source, shows them next to admin grants, with the operator as granter; source=studio_grant or source=grant tells them apart), and are not counted against the daily ceiling for admin grants. No daily ceiling applies: a studio may give all of its budget at once, and the budget is what bounds it (new budget has its own daily ceiling). A single grant may give at most STUDIO_GRANT_MAX_CENTS (fail-closed: grants are refused with a 503 while it is unset). The grant is refused when USD credits are disabled, when it is above that ceiling, when the studio is paused, when the player is one of the studio's operators (the granter included), when the studio's balance does not cover it, and, judged last so the refusal cannot be used to look a flag up, when the player cannot receive a studio's credits. The studio's checks are made in the transaction that writes the grant, under the studio's lock, so concurrent grants cannot overdraw a budget, and adding or removing an operator waits for a grant in flight.
Idempotent on idempotencyKey: repeating a request with the same key and body answers 200 with replayed: true and the credit the first request granted, and writes nothing. A repeat is answered before any check that only applies to a new grant, so it is answered even if the studio has since been paused or emptied, the player flagged, USD credits turned off or the ceiling lowered. The same key with a different body is refused. Keys are unique per studio, not per operator: another operator of the same studio repeating a key with the same body is answered the same grant. A new grant is announced on Slack and published as an ON_DEMAND_CREDITS_GRANTED event whose metadata also carries studioId and studioName; a replay is not.
Each operator wallet may send at most STUDIO_GRANT_RATE_LIMIT grants (60 by default) per STUDIO_GRANT_RATE_WINDOW_SECONDS (60 by default); past that it is answered 429 with Retry-After, and nothing is written.
Signed fetch authentication using @dcl/platform-crypto-middleware (ADR-44l). Requires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation. See http://adr.decentraland.org/adr/ADR-44l for details.
The player's wallet
^0x[a-fA-F0-9]{40}$At most STUDIO_GRANT_MAX_CENTS / 10 (see grantLimits on GET /admin/studios/{studioId})
Trimmed, a single line; recorded on the grant and on the studio's budget entry
Trimmed, a single line of printable characters; recorded on the grant
The caller's key for this grant, e.g. a new UUID; reuse it only to retry it
^[A-Za-z0-9._:-]{8,128}$The key already made this grant; nothing new was written
The studio's balance now (after the grant, or as it stands on a replay)
True when the idempotency key had already made this grant
Credits granted
Invalid studio id or request body
STUDIO_OPERATOR: the player acts for the studio.
STUDIO_NOT_FOUND: no studio with that id, or the signing wallet does not act for it.
USD_CREDITS_DISABLED: Shop USD credits are off.
STUDIO_PAUSED, STUDIO_BUDGET_EXCEEDED (the balance does not cover it), GRANT_LIMIT_EXCEEDED (above the
per-grant ceiling), RECIPIENT_NOT_ELIGIBLE (the player cannot receive a studio's credits; the reason is
not given, and it is only judged once the grant would otherwise be made) or IDEMPOTENCY_KEY_REUSED (the
key was used for a different request).
Too many grants from this operator wallet; nothing was written. Retry after Retry-After seconds.
Internal server error
GRANTS_NOT_CONFIGURED: no per-grant ceiling (STUDIO_GRANT_MAX_CENTS) is configured
POST /operator/studios/{studioId}/grants HTTP/1.1
Host: credits.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 160
{
"address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb0",
"credits": 300,
"reason": "Top player of the week",
"idempotencyKey": "3d1c0f5e-8b2a-4f6e-9c7d-1a2b3c4d5e6f"
}{
"creditId": "text",
"studioId": "123e4567-e89b-12d3-a456-426614174000",
"address": "text",
"denomination": "USD",
"credits": 1,
"usdCents": 1,
"balanceCents": 1,
"replayed": true
}Last updated