API to request and monitor drips (USDFC)

[LesnyRumcajs]

Summary

Implement an API to get tokens programmatically. The most pressing token is USDFC; the native calibnet token doesn't have to be implemented, for now.

One server-side method needed:

• get tokens
  • address and faucet type as input (perhaps other params if needed)
  • The endpoint should still use the same limits as the regular faucet (so user can't provide their own faucet settings...)
  • done completely server-side, including communication with RPC nodes.
  • non-blocking, should return tx id

sequenceDiagram
    participant Client
    participant API_Server as API Server
    participant RPCNode as RPC Node

    Client->>API_Server: POST /getTokens(address, faucetType)
    API_Server->>API_Server: Validate input (strict rules)
    API_Server->>API_Server: Check faucetType (reject mainnet)
    API_Server->>API_Server: Enforce faucet limits
    API_Server->>API_Server: Create transaction
    API_Server->>API_Server: Sign transaction
    API_Server->>RPCNode: Submit signed transaction
    RPCNode-->>API_Server: Return tx id
    API_Server-->>Client: 200 OK + { txId }

Loading

Brainstorm some better naming, but we want this API to be stable once it's there.

Given that Leptos already generates a proper server API, it may generate some docs.

It'd be great for the faucet to use this API normally, but it can be done in a follow-up task if it speeds things up.

Completion Criteria

• Design an ergonomic API to request faucet funds (USDFC is the most important here, native token can be done in follow-up)
• The method is implemented and tested
• Strict validation of inputs (should be already in place, but please check)
• Automatic tests are in place
• Security considerations - mainnet drip should not be available programmatically (or should always return an error 418)
• Documentation and example usage in the form of a markdown document
• FS WG informed and confirmation received, these are the droids they are looking for.

Additional Links & Resources

This is a request from the Filecoin Services WG. If unsure on the API ergonomics, reach out to them as they'll be the first consumer of this API.