Merge pull request #246 from ubq-testing/refactor/readme

fix: readme
ubiquity · Jun 17, 2024 · 114e59a · 114e59a
2 parents b7dd348 + 692064b
commit 114e59a
Showing 1 changed file with 61 additions and 58 deletions.
diff --git a/README.md b/README.md
@@ -1,85 +1,88 @@
-# Generate Permit
+# [pay.ubq.fi](https://pay.ubq.fi)
 
-Tool for generating offline permits for bounty hunters to withdraw their payments.
+A vanilla Typescript dApp for claiming Ubiquity Rewards. It also includes tools for generating and invalidating permits and can be used to claim both ERC20 and ERC721 tokens.
 
-## How to set up
+## Setup Local Testing Environment
 
-Create a `.env` file in the project root:
+1. Install [Foundry](https://book.getfoundry.sh/getting-started/installation).
+2. Create a `.env` file in the project root with the following settings:
+- These are the suggested default test environment variables that allow for local setup using the supplied yarn commands. If you want to produce or invalidate real on-chain permits you must change the below values to reflect the real permit information such as address, chain ID, private key and so on.
 
-```
-# common variables
-CHAIN_ID="" # mainnet: 1, goerli: 5
-FRONTEND_URL=""
-UBIQUIBOT_PRIVATE_KEY=""
-RPC_PROVIDER_URL=""
-PAYMENT_TOKEN_ADDRESS="" # // DAI address, mainnet: 0x6b175474e89094c44da98b954eedeac495271d0f, goerli: 0x11fE4B6AE13d2a6055C8D9cF65c55bac32B5d844
-# variables depending on spender (bounty hunter)
-AMOUNT_IN_ETH="1" # amount in ether, 1 AMOUNT_IN_ETH = 1000000000000000000 WEI
-BENEFICIARY_ADDRESS=""
-```
+    ```env
+    # Common variables
+    CHAIN_ID="31337"
+    FRONTEND_URL="http://localhost:8080"
+    UBIQUIBOT_PRIVATE_KEY="0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d"
+    RPC_PROVIDER_URL="http://127.0.0.1:8545"
+    PAYMENT_TOKEN_ADDRESS="0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d"
+    
+    # Variables depending on spender (bounty hunter)
+    AMOUNT_IN_ETH="1"
+    BENEFICIARY_ADDRESS="0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+    ```
 
-## How it works
+## Local Testing
 
-1. Admin sets `env.AMOUNT_IN_ETH` and `env.BENEFICIARY_ADDRESS` depending on a bounty hunter's reward and address
-2. Admin generates an offline permit URL via `npx tsx generate-permit2-url.ts`. Permit URL example:
+1. Set `.env` variables.
+2. Run `yarn test:anvil` in terminal A and `yarn test:fund` in terminal B.
+3. In terminal B, run `yarn start`.
+4. A permit URL for both ERC20 and ERC721 will be generated.
+5. Open the generated permit URL from the console.
+6. Connect your wallet (import anvil accounts [0] & [1] into your wallet).
+7. Depending on your connected account, either the claim or invalidate button will be visible.
+8. To test ERC721 permits, deploy the `nft-rewards` contract from the [repository](https://github.com/ubiquity/nft-rewards).
 
-```
-http://localhost:8080?claim=eyJwZXJtaXQiOnsicGVybWl0dGVkIjp7InRva2VuIjoiMHgxMWZFNEI2QUUxM2QyYTYwNTVDOEQ5Y0Y2NWM1NWJhYzMyQjVkODQ0IiwiYW1vdW50IjoiMTAwMDAwMDAwMDAwMDAwMDAwMCJ9LCJub25jZSI6IjQ0NTUxMjc4NTQwNTU0MzM1MDQ2NzU2NDQ3MzM2MjI1ODg5OTE4OTY5MTczODQwNTU0Nzk2NzQ3MzQzMzAwOTg0NzU4MDIyMzY1ODczIiwiZGVhZGxpbmUiOiIxMTU3OTIwODkyMzczMTYxOTU0MjM1NzA5ODUwMDg2ODc5MDc4NTMyNjk5ODQ2NjU2NDA1NjQwMzk0NTc1ODQwMDc5MTMxMjk2Mzk5MzUifSwidHJhbnNmZXJEZXRhaWxzIjp7InRvIjoiMHhjODZhMDU5NzgwMThlMDRkNmVGMmFhNzNFNjlhNzMzQzA2ZDFmODllIiwicmVxdWVzdGVkQW1vdW50IjoiMTAwMDAwMDAwMDAwMDAwMDAwMCJ9LCJvd25lciI6IjB4NTRmNGEzNjQyMkRjOTZkMDg0OTY3NWMxZjBkZDJCOTZEMjc1NThFMiIsInNpZ25hdHVyZSI6IjB4NWI0OTE5MjhmYzI4MzBlMjZiNTViMWUxOWQ3YzVhMmVjNGE2ZmRhYWI1OGFiYjgyOWMwNmYzYzlkNGE4YTc5YjAzYmE2NjlkMDM4YjFmYzg5NjgzYzMyYjBiYTA5MzU2MDRjMGU1MDNjYWE3ZmY2ZWM2MDg2ZWZlYjY2MTY5MjQxYyJ9
-```
+### Importing Anvil Accounts
 
-3. Admin posts offline permit URL in issue comments
-4. Bounty hunter opens permit URL, connects wallet and clicks a "withdraw" button to get a payment
+1. Open your wallet provider and select `import wallet` or `import account`.
+2. Obtain the private keys by running `anvil` or using the yarn command.
+3. Copy and paste the private keys into your wallet provider.
 
-## How to test locally
+### Expected Behavior
 
-1. Set `.env` variables.
-2. Run `anvil --chain-id 31337 --fork-url https://rpc.gnosis.gateway.fm` in a separate terminal.
-3. Run the Anvil commands (uses the Anvil default wallets).
-4. In the project root run `yarn start`.
-5. A permit URL for both ERC20 and ERC721 is generated in the terminal.
-6. Open the generated permit URL defaulting to the variable values in the `.env` file.
-7. Connect the bounty hunter's address.
-8. Click the "withdraw" button to get a reward.
-9. Testing the ERC721 permit is easiest deploying the `nft-rewards` contract from the [repository](https://github.com/ubiquity/nft-rewards)
+#### Setup
 
-#### Anvil commands
+- A local blockchain instance will be created for testing.
+- The permit URL will be generated in the console. Ensure your console has enough space for the full URL.
+- Imported anvil accounts [0] & [1] can claim and invalidate permits.
 
-###### Using any other `--chain-id` will hit real RPC endpoints.
+#### Claiming
 
-```shell
-cast rpc anvil_impersonateAccount 0xba12222222228d8ba445958a75a0704d566bf2c8 &
-cast send 0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d --unlocked --from 0xba12222222228d8ba445958a75a0704d566bf2c8 "transfer(address,uint256)(bool)" 0x70997970C51812dc3A010C7d01b50e0d17dc79C8  337888400000000000000000 &
-cast send 0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d --unlocked --from 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 "approve(address,uint256)(bool)" 0x000000000022D473030F116dDEE9F6B43aC78BA3  9999999999999991111111119999999999999999 &
-cast send 0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d --unlocked --from 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 "approve(address,uint256)(bool)" 0x000000000022D473030F116dDEE9F6B43aC78BA3  999999999999999111119999999999999999
+- Uses chain id `31337` and RPC provider `http://localhost:8545`.
+- Claiming involves transferring tokens from the signer's account to the beneficiary's account.
+- Signer must have signed a permit and have enough balance approved for the permit2 contract.
 
-```
+#### Invalidating
 
-## CloudFlare Setup (GitHub Secrets)
+- Only the permit signer can invalidate it.
+- Invalidating calls `invalidateUnorderedNonces` on the `Permit2` smart contract.
 
-##### CLOUDFLARE_ACCOUNT_ID =
+### Considerations
 
-    https://dash.cloudflare.com/***/pages
-    https://dash.cloudflare.com/abcd1234/pages
-    (Here `abcd1234` is your account ID)
+- MetaMask is considered the default wallet provider.
+- Ensure correct network selection in your wallet (`http://localhost:8545` with chain id `31337`).
+- Use MetaMask Mobile Wallet Browser for mobile testing.
 
-##### CLOUDFLARE_API_TOKEN =
+### Errors
 
-    https://dash.cloudflare.com/profile/api-tokens > Create Token > API token templates > Edit Cloudflare Workers > Use Template
-    Account Resources = All Accounts or Target Account
-    Zone Resources = All Zones
-    (Detailed Instructions: https://developers.cloudflare.com/workers/wrangler/ci-cd/)
+- Clear transaction history in MetaMask if transactions hang after restarting the Anvil instance.
+- The test suite may show error toasts due to MetaMask spoofing.
+- Ensure `.env` is correctly configured and wallet provider network is correct if `Allowance` or `Balance` is `0.00`.
+- Always start the Anvil instance before using `yarn start` as permit generation requires an on-chain call to `token.decimals()`.
 
-##### CLOUDFLARE_ASSET_DIRECTORY =
+## How to generate a permit2 URL using the script
 
-    static
+1. Admin sets `env.AMOUNT_IN_ETH` and `env.BENEFICIARY_ADDRESS` depending on a bounty hunter's reward and address
+2. Admin generates an offline permit URL via `npx tsx generate-permit2-url.ts`. Permit URL example:
 
-##### CLOUDFLARE_PROJECT_NAME =
+```
+http://localhost:8080?claim=eyJwZXJtaXQiOnsicGVybWl0dGVkIjp7InRva2VuIjoiMHgxMWZFNEI2QUUxM2QyYTYwNTVDOEQ5Y0Y2NWM1NWJhYzMyQjVkODQ0IiwiYW1vdW50IjoiMTAwMDAwMDAwMDAwMDAwMDAwMCJ9LCJub25jZSI6IjQ0NTUxMjc4NTQwNTU0MzM1MDQ2NzU2NDQ3MzM2MjI1ODg5OTE4OTY5MTczODQwNTU0Nzk2NzQ3MzQzMzAwOTg0NzU4MDIyMzY1ODczIiwiZGVhZGxpbmUiOiIxMTU3OTIwODkyMzczMTYxOTU0MjM1NzA5ODUwMDg2ODc5MDc4NTMyNjk5ODQ2NjU2NDA1NjQwMzk0NTc1ODQwMDc5MTMxMjk2Mzk5MzUifSwidHJhbnNmZXJEZXRhaWxzIjp7InRvIjoiMHhjODZhMDU5NzgwMThlMDRkNmVGMmFhNzNFNjlhNzMzQzA2ZDFmODllIiwicmVxdWVzdGVkQW1vdW50IjoiMTAwMDAwMDAwMDAwMDAwMDAwMCJ9LCJvd25lciI6IjB4NTRmNGEzNjQyMkRjOTZkMDg0OTY3NWMxZjBkZDJCOTZEMjc1NThFMiIsInNpZ25hdHVyZSI6IjB4NWI0OTE5MjhmYzI4MzBlMjZiNTViMWUxOWQ3YzVhMmVjNGE2ZmRhYWI1OGFiYjgyOWMwNmYzYzlkNGE4YTc5YjAzYmE2NjlkMDM4YjFmYzg5NjgzYzMyYjBiYTA5MzU2MDRjMGU1MDNjYWE3ZmY2ZWM2MDg2ZWZlYjY2MTY5MjQxYyJ9
+```
 
-    npm install -g wrangler
-    wrangler login
-    wrangler pages project create
+3. Admin posts offline permit URL in issue comments (with the payment portal domain name)
+4. Bounty hunter opens permit URL, connects wallet and clicks a "withdraw" button to get a payment
 
-## How to invalidate a permit2 nonce by example
+## How to invalidate a permit2 nonce using the script
 
 This section describes how to invalidate the following [permit](https://github.com/ubiquity/ubiquity-dollar/issues/643#issuecomment-1607152588) (i.e. invalidate a permit2 nonce)