@opengsn/captcha-paymaster
v0.0.9
Published
A sample paymaster that pays only for validate captcha
Downloads
4
Readme
Captcha Support for Paymaster
This project demonstrate how a paymaster can use an external service (CAPTCHA) to avoid spam from anonymous calling users. The paymaster agrees to pay for requests, but wants to make sure a user can't abuse it.
This project adds captcha check to paymaster requests
It involves 3 components:
A CaptchaPaymaster: a paymaster that requires a signed approvalData before it accepts a request.
Captcha validation service, which takes the captcha response from the webapp, validates it with google, and generates a signed approvalData acceptable by the paymaster.
The webapp, which uses "Google Recaptcha", the validation service and the CaptchaPaymaster.
Usage
The paymaster in this project accepts all requests. You might want to fork it, inherit the CaptchaPaymaster, and add your restriction (e.g. limit only to specific target contract)
register with Google's Captcha service https://www.google.com/recaptcha/admin/create
- The example below uses reCaptcha v2 (with "I'm not a robot" button).
For testing purposes, you can deploy the validation service locally, by installing
netlify-cli
Deploy the validation server. This project is deployable directly to netlify. It is already deployed as gsn-captcha-paymaster.netlify.app
Note that you need to provide 2 environment variables to the netlify app:
RECAPTCHA_SECRET_KEY
- google's recaptcha secret keyPRIVATE_KEY
- the private key that signs the approval
Without these items, the netlify deployment would fail.
Go back to Google's reCaptcha admin page, and update the netlify URL you deployed to (you can add
localhost
for testing)Deploy the CaptchaPaymaster. Through truffle console, it can be deployed with:
paymaster = await CaptchaPaymaster.new(signer,url, "captcha:")
signer
- the address of the signer (for the above private key)url
of the the above validation service. e.g. 'https://gsn-captcha-paymaster.netlify.app/.netlify/functions/validate-captcha',- prefix for signing. currently has to be "captcha:"
- make sure to connect it to the RelayHub and fund it.
Add "recaptcha" button to your webapp (see
html/index.html
for sample)in you webapp, define your
RelayProvider
to use the above paymaster, and use the generated approval data:import { createCaptchaAsyncApprovalCallback } from '@opengsn/captcha-paymaster' ... gsnProvider = new RelayProvider(provider, { ..., paymasterAddress: myCaptchaPaymasterAddress }, { asyncApprovalData: createCaptchaAsyncApprovalCallback(web3, async() => grecaptcha.getResponse()) })
Now transactions will only pass through if the user successfully proven he's not a robot...
Technical Application flow
This is what happens under the hood:
- The user has to click the "I'm not a robot" button. In the background, a new captcha response is created.
- When clicking the "Action" button, the RelayProvider attempts to create a request, and calls asyncApprovalData callback.
- the callback calls a read function on the provider, to collect user's address, nonce, and current timestamp
- Then the callback then calls the captcha validation service with the above user data.
- The validation service uses Google API to validate the captcha, and signs the user's data and timestamp.
- The RelayProvider can now use the returned "approvalData", and pass it with the next GSN request.
- When processing this request, the paymaster validates the content is valid (time not expired, user and nonce matches the request) and that the signature is valid.
- The paymaster approves the request, and the transaction can be processed.
Note that in this sample, we explicitly don't attempt to refresh the captcha automatically: If you dont press the "I'm not a robot" checkbox, a request will be sent with last captcha value, which might be stale or completely invalid. This comes to demonstrate that its not the client that validates the captcha, but the paymaster