diff --git a/methods/http/requestAirdrop.md b/methods/http/requestAirdrop.md new file mode 100644 index 0000000..67603c2 --- /dev/null +++ b/methods/http/requestAirdrop.md @@ -0,0 +1,11 @@ +# requestAirdrop + +Requests a transfer from the RPC node configured faucet and returns its submitted transaction signature. + +## Semantics + +The RPC node must have a faucet configured; otherwise Agave returns JSON-RPC InvalidRequest. The optional recentBlockhash is verified when supplied. If omitted, Agave selects the confirmed bank last blockhash. The returned signature only acknowledges submission; clients must confirm it separately. + +## Implementation notes + +- [**Agave**](../../implementations/agave.md): reference implementation. See the pinned [handler](https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc.rs#L3868-L3922). diff --git a/methods/http/requestAirdrop.yaml b/methods/http/requestAirdrop.yaml new file mode 100644 index 0000000..e687647 --- /dev/null +++ b/methods/http/requestAirdrop.yaml @@ -0,0 +1,41 @@ +name: requestAirdrop +status: standard +summary: Requests a faucet-funded transfer to an account. +params: + - name: pubkey + required: true + summary: Recipient account public key. + schema: { $ref: '#/components/schemas/Pubkey' } + - name: lamports + required: true + summary: Lamports requested from the faucet. + schema: { $ref: '#/components/schemas/U64' } + - name: config + required: false + summary: Optional recent blockhash and commitment. + schema: + type: object + properties: + recentBlockhash: { $ref: '#/components/schemas/Hash' } + commitment: { $ref: '#/components/schemas/Commitment' } +result: + name: signature + summary: Base-58 signature of the submitted faucet transaction. + schema: { $ref: '#/components/schemas/Signature' } +errors: + - $ref: '#/components/errors/InvalidParams' +examples: + - name: devnet-airdrop + summary: Request one SOL from a configured faucet. + params: + - name: pubkey + value: "Vote111111111111111111111111111111111111111" + - name: lamports + value: 1000000000 + result: + name: signature + value: "5j7sZ3h5xKk9NqYyVVEaVFWuXGKRyuiz5ZvM8QW5goFJ5Yzx6N9fP5qDqDtwaENmJ3wYJ8Bwdz3KznipwHtQpJQm" +implementations: + agave: { status: full } + cloudbreak: { status: none } + superbank: { status: none } diff --git a/proposals/0042-request-airdrop.md b/proposals/0042-request-airdrop.md new file mode 100644 index 0000000..e2585ef --- /dev/null +++ b/proposals/0042-request-airdrop.md @@ -0,0 +1,39 @@ +--- +number: 0042 +title: Add requestAirdrop method specification +authors: [rpcpool] +status: draft +created: 2026-09-14 +reference-implementations: + - https://github.com/anza-xyz/agave/tree/6dd9d38771e46103b9680357a855804165612602 +--- + +# Add requestAirdrop method specification + +## Summary + +Add the public requestAirdrop RPC method. + +## Motivation + +Clients need a portable contract for this public Agave RPC method. + +## Specification + +Add the paired HTTP method files. The method accepts a recipient, lamports, and optional blockhash and commitment configuration, then returns the submitted signature. + +## Return-type impact + +Adds the result shape defined by the paired method source. + +## Compatibility + +This is additive. Agave conforms. Cloudbreak and Superbank do not serve the method. + +## Reference implementation + +- [Agave implementation](https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc.rs#L3868-L3922) + +## Security considerations + +Airdrops spend faucet funds. Operators must rate limit and expose this method only on intended development networks. diff --git a/spec-info.yaml b/spec-info.yaml index 892ea85..bca4391 100644 --- a/spec-info.yaml +++ b/spec-info.yaml @@ -1,5 +1,5 @@ title: Solana JSON-RPC API -version: 0.1.0 +version: 0.2.0 license: name: MIT url: https://opensource.org/license/mit/