Faucet

체인에 쓰는 유일한 퍼스트파티 서비스입니다. 운영자 키를 들고 있으면서 드립을 대신 제출하며, 그래서 지갑이 필요 없습니다 - 그리고 그래서 할당량이 호출자와 그 키 사이에 있는 유일한 것입니다.

무엇을 하는가

주소를 POST하면 서비스가 자기 할당량을 확인하고, 운영자 키로 Faucet 컨트랙트 호출에 서명하고, 그것을 제출한 뒤 영수증을 기다렸다가 답합니다. 페이지에 지갑도 없고 여러분의 서명도 없습니다. 그 트랜잭션이 여러분의 것이 아니기 때문입니다.

인증이 없으면서 진짜 키를 씁니다

토큰도, 캡차도, 서명도 없습니다. 인증을 대신하는 것은 무엇이 서명되기 전에 미리 잡히는 세 개의 할당량과, 컨트랙트 자신이 강제하는 쿨다운입니다. 그래서 하나를 통과한 호출자도 다른 하나를 만납니다. 여기의 어느 것도 여러분이 누구인지에 대한 증명이 아닙니다.

그 라우트 중 둘 - 드립과 상태 - 은 프로젝트 홈 출처에도 다시 노출되어 있으므로, 거기의 페이지는 출처를 넘는 호출 없이 그것을 쓸 수 있습니다.

베이스 URL과 CORS

엔드포인트	Value
공개	https://faucet.picklechain.xyz서비스가 같은 출처에서 자기 정적 페이지를 제공합니다
다시 노출된 것	POST /drip and GET /faucet-status프로젝트 홈 출처에서 같은 서비스로 프록시됩니다
직접 운영하는 스택	http://127.0.0.1:3000
CORS	허용 목록OPTIONS는 POST, GET, OPTIONS를 허용하며 204로 답합니다. 목록에 없는 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.

bash

# 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는 컨트랙트의 쿨다운이고, 자정이 아니라 마지막 드립부터 세며, 기다릴 간격을 자기 메시지에 실어 나릅니다. 미리 볼 수 있는 것은 두 번째뿐입니다. POST하기 전에 /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은 트랜잭션이 나갔다가 실패했다는 뜻일 수도, 나갔는데 폴링 창 안에 영수증이 오지 않았다는 뜻일 수도 있습니다. 어느 쪽이든 할당량 예약은 되돌려지므로 재시도는 허용됩니다. 다만 그 트랜잭션은 여전히 착지할 수 있습니다. 가정하지 말고 그 주소의 잔액을 체인에서 폴링하십시오.