開発者へ / アプリケーション API
フォーセット
チェーンに書き込む唯一のファーストパーティのサービスです。運営者の鍵を持ち、あなたの代わりに drip を提出します。だからウォレットが要らないのであり、だから呼び出し側とその鍵の間にあるのは割り当てだけなのです。
何をするか
アドレスを POST すると、サービスは自分の割り当てを確認し、運営者の鍵でフォーセットの コントラクトへの呼び出しに署名し、それを提出し、レシートを待ってから答えます。ページに ウォレットはなく、あなたからの署名もありません。そのトランザクションはあなたのものでは ないからです。
認証がなく、そして本物の鍵を使います
トークンも、キャプチャも、署名もありません。認証の代わりを務めるのは、何かに署名する前に確保される三つの割り当てと、コントラクト自身が強制するクールダウンです。 だから一つをすり抜けた呼び出し側も、もう一つにぶつかります。ここには、あなたが誰かに ついて何かを証明するものは一つもありません。
二つのルートはプロジェクトのホームのオリジンにも再公開されています。drip と status で、 そちらのページがクロスオリジンの呼び出しなしに使えるようにするためです。
ベース URL と CORS
| エンドポイント | Value |
|---|---|
| 公開 | https://faucet.picklechain.xyzサービスは自身の静的ページも同じオリジンから提供します |
| 再公開 | POST /drip と 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.
# 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 |
|---|---|
| クライアントのアドレスごと | 1 日 5 回転送されたクライアントのアドレスでキーが付きます |
| 資金を受け取るアドレスごと | 1 日 2 回本文の中のアドレスでキーが付きます |
| 全体 | 1 日 1000 回加えて、通算の別の予算があります |
| オンチェーンのクールダウン | アドレスごとに 1 日コントラクトが強制し、サービスが覚えているのではなくチェーンから読まれます |
二つの異なる拒否は、二つの異なることを意味します
429 はサービス自身の日ごとの割り当てで、日付が変わればリセットされます。409 はコントラクトのクールダウンで、真夜中からではなく最後の drip から 数えられ、待つべき間隔をメッセージに載せます。前もって見えるのは後者だけです。 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 は、トランザクションが出てから失敗したか、出たのに ポーリングの窓のうちにレシートが届かなかったかのどちらかでありえます。割り当ての確保は どちらの場合も巻き戻されるので、再試行そのものは許されています。ただしトランザクションは まだ着地するかもしれません。決めつけずに、そのアドレスの残高をチェーンに問い合わせて ください。