Для разработчиков / API приложений
Кран
Единственный собственный сервис, который пишет в цепочку. Он держит ключ оператора и отправляет выдачу за вас, поэтому ему не нужен кошелёк - и поэтому квота есть единственное, что стоит между вызывающим и этим ключом.
Что он делает
Вы отправляете адрес; сервис проверяет собственную квоту, подписывает вызов контракта крана ключом оператора, отправляет его и ждёт квитанцию, прежде чем ответить. На странице нет кошелька и нет вашей подписи, потому что транзакция не ваша.
Без аутентификации, и он тратит настоящий ключ
Ни токена, ни капчи, ни подписи. Вместо аутентификации стоят три квоты, зарезервированные до того, как что-либо подписано, плюс период ожидания, который навязывает сам контракт, так что вызывающий, проскочивший одно, всё равно встретит другое. Ничто здесь не является доказательством чего бы то ни было о том, кто вы.
Два его маршрута также переизданы на домашнем origin проекта - выдача и статус - чтобы страница оттуда могла ими пользоваться без кросс-origin вызова.
Базовый URL и CORS
| Точка доступа | Value |
|---|---|
| Публично | https://faucet.picklechain.xyzсервис отдаёт собственную статическую страницу с того же origin |
| Переиздано | POST /drip и GET /faucet-statusна домашнем origin проекта, проксируется в тот же сервис |
| Ваш собственный стек | http://127.0.0.1:3000 |
| CORS | список разрешённыхOPTIONS отвечает 204, разрешая POST, GET и OPTIONS; Origin вне списка получает отказ 403 |
Всё, что не на маршрутах API и не в явном списке разрешённой статики, даёт 404 - никогда 403, потому что отказ, который различает эти два случая, подтверждает, что файл существует.
Маршруты
/status
GET- Params
- address (optional)
- Возвращает
- {faucet, pickle, ethAmount, bxAmount, ethAmountEth, bxAmountBx, treasuryEth, treasuryBx, treasuryEthFmt, treasuryBxFmt, cooldown, evmBlock, miniBlock}
The faucet and token addresses, the drip amounts in both base units and display units, what is left in the treasury and the cooldown in seconds. Pass `?address=` and it also answers `canDrip`, `retryIn` and a formatted `retryIn`.
Также по адресу. GET /faucet-status
Полезно знать. The `bx`-prefixed keys are the PKL amounts. The names are historic and the SERVICE still emits them; the formatted string beside them says PKL. 502 when the node is unreachable, 500 for anything else.
/drip
POST- Params
- body {"address": "0x..."}
- Возвращает
- {hash, address}
Reserves quota, signs `dripTo` with the operator key, submits it and polls for the receipt before answering. No authentication of any kind.
Полезно знать. It waits for the receipt: about three seconds of polling before it gives up with `no receipt yet`. A quota reservation is ROLLED BACK when the send fails, so a failed attempt does not cost you a daily slot.
/addresses
GET- Params
- none
- Возвращает
- the deployment manifest, as JSON
Streams the manifest file straight through. This is where an application discovers what is deployed.
Также по адресу. GET /op-deployment/l2-addresses.json
Полезно знать. 404 with a JSON body when the file cannot be read, which is also what you get before a deployment has written it.
any
OPTIONS- Params
- none
- Возвращает
- 204
Allowed methods are POST, GET and OPTIONS; the allowed header is content-type.
Полезно знать. 403 when an Origin is present and not on the allowlist.
# What is left, and whether this address may claim right now.
curl -s "$FAUCET/status?address=$ADDR" | jq '{canDrip, retryIn, retryInFmt, treasuryEthFmt}'
# The claim. A body is required: a zero-length one answers 413, not 400.
curl -s -X POST "$FAUCET/drip" \
-H 'content-type: application/json' \
-d "{\"address\":\"$ADDR\"}"
# 200 -> {"hash": "0x…", "address": "0x…"}; the receipt has already been seen.Квота
Quota is RESERVED before the transaction is signed and committed only once a hash comes back, so two simultaneous requests cannot both pass the check. The journal that backs it is an append-only file outside the served directory, rotated by size and by age, with a checkpoint at the head of each new file so the all-time total survives both rotation and a restart.
| Бюджет | Value |
|---|---|
| На клиентский адрес | 5 в деньс ключом по переданному клиентскому адресу |
| На пополняемый адрес | 2 в деньс ключом по адресу в теле запроса |
| Глобально | 1000 в деньи отдельный бюджет за всё время |
| Ончейн-период ожидания | один день на адреснавязан контрактом и читается из цепочки, а не запоминается в сервисе |
Два разных отказа значат две разные вещи
429 - это собственная суточная квота сервиса, и она сбрасывается на переломе суток. 409 - это период ожидания контракта, он считается от последней выдачи, а не от полуночи, и несёт в своём сообщении интервал ожидания. Заранее виден только второй: спросите /status?address= и прочитайте canDrip и retryIn перед отправкой.
The per-address budget is keyed on the FUNDED address and the per-client one on the address the request came from, read from the right-hand end of the forwarded chain. Put a cache in front without telling the service how many proxies it now sits behind and every visitor collapses into one bucket.
Ошибки
| Статус | Значение |
|---|---|
| 400 | invalid json, invalid address, invalid content lengthand a chunked request, which the handler refuses outright |
| 409 | cooldownthe message carries the interval to retry in. The cooldown is enforced by the contract, one day per address, and is read from the chain rather than remembered here |
| 413 | payload too largethe cap is 4096 bytes - and a ZERO-LENGTH body answers 413 as well, which reads as the opposite of what happened. Send a body |
| 429 | quota exceeded5 a day per address seen, 2 a day per funded address, 1000 a day globally; the message says which one you hit |
| 502 | upstream RPC unavailablethe node did not answer. Nothing was signed |
| 503 | faucet empty, or the drip failedthe message names the remaining balance when it is a funding problem, and is the opaque `drip failed` otherwise |
503 после отправки - не безопасный повтор
502 означает, что узел так и не ответил и ничего не было подписано - этот повторяйте свободно. 503 может значить, что транзакция ушла и потом упала, или что она ушла и квитанция не пришла в окно опроса. Резервирование квоты откатывается в обоих случаях, так что повтор разрешён; транзакция всё равно может приземлиться. Опрашивайте цепочку на предмет баланса адреса, а не стройте предположений.