{"id":13767654,"url":"https://github.com/etherspot/arka","last_synced_at":"2026-04-05T18:02:51.343Z","repository":{"id":210925973,"uuid":"663163324","full_name":"etherspot/arka","owner":"etherspot","description":"ARKA - (Albanian for Cashier's case) is the first open source \"Paymaster\" as a service software.","archived":false,"fork":false,"pushed_at":"2025-04-02T13:25:01.000Z","size":2968,"stargazers_count":58,"open_issues_count":14,"forks_count":9,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-09T20:09:38.290Z","etag":null,"topics":["account-abstraction","eip4337","erc4337","paymaster"],"latest_commit_sha":null,"homepage":"https://arka.etherspot.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/etherspot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-06T17:38:45.000Z","updated_at":"2025-04-07T20:51:40.000Z","dependencies_parsed_at":"2024-06-27T15:15:14.114Z","dependency_job_id":"d0eb892e-95ec-4f71-9443-221d003f3e63","html_url":"https://github.com/etherspot/arka","commit_stats":{"total_commits":100,"total_committers":9,"mean_commits":11.11111111111111,"dds":"0.45999999999999996","last_synced_commit":"ccacb0bd6e51ae7c2d5d057e6cc978f2402c18e6"},"previous_names":["etherspot/arka"],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etherspot%2Farka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etherspot%2Farka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etherspot%2Farka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etherspot%2Farka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/etherspot","download_url":"https://codeload.github.com/etherspot/arka/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103871,"owners_count":21048245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["account-abstraction","eip4337","erc4337","paymaster"],"created_at":"2024-08-03T16:01:10.679Z","updated_at":"2026-04-05T18:02:46.309Z","avatar_url":"https://github.com/etherspot.png","language":"TypeScript","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eARKA\u003c/h1\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://public.etherspot.io/assets/etherspot.gif\" width=\"200\" height=\"200\"\u003e\n  \u003cp\u003e\n    \u003cb\u003e\n      ARKA (Albanian for Cashier's case) is open source \"Paymaster\" as a service software.\n    \u003c/b\u003e\n   \u003c/p\u003e\n\u003c/div\u003e\n\n--------------\n\n\u003e[!IMPORTANT]\n\u003eThis repo/software is under active development.\n\n## 💸 Arka\n\nArka paymaster is an open source piece of infrastructure which is a vital piece of\nthe [ERC-4337 stack](https://www.erc4337.io/). \n\nPaymasters are what is needed to sponsor users \ntransactions.\n\nThe flow is as follows:\n- Use Etherspot's hosted version of Arka (https://arka.etherspot.io/) or deploy your own.\n- [Whitelist](https://etherspot.fyi/arka/api-calls/whitelisting) an address you want to sponsor.\n- [Deposit](https://etherspot.fyi/arka/api-calls/deposit) to the paymaster.\n- Include the paymaster data in the [UserOp](https://etherspot.fyi/account-abstraction/userops) to have the transaction sponsored.\n\n## 🐳 How to run (a Docker image)\n\n## Prerequisites\n* Docker Installed (https://www.docker.com/get-started/)\n* Edit docker-compose.yml for backend cron job and put a value in CRON_PRIVATE_KEY with the wallet private key you want to use to periodically update the paymaster contract price\n\n#### `docker compose up`\n\nThis would spin up three services at once which will be available on these urls:\n- http://localhost:3002 (Arka Admin Frontend)\n- http://localhost:3000 (Arka Frontend for EndUser)\n- http://localhost:5050 (Arka backend for Api service)\n\n## Local Configuration Changes\n\nThere is an option to run the code locally without using AWS and only using local SQLite. These are the following steps to follow for using local SQLite database for apiKey and frontend to sync up\n\n* Edit the docker-compose.yml to change the UNSAFE_MODE variable under backend to be true\n* Run `docker compose up`\n* Once its running, go to `http://localhost:3002/apiKey` and add the necessary apiKey and its private Key to store it to the local sqlite. Please Note that the privateKey will be stored in encrypted format with the mac address as the secret string for encryption and decryption process\n* NOTE: The SUPPORTED_NETWORKS and ERC20_PAYMASTERS parameters require to input in base64 format and the original structure is described as follows\n- SUPPORTED_NETWORKS - the networks you wish to support. The structure should follow this file config.json which again needs to be converted into `base64` value\n- ERC20_PAYMASTERS - the custom deployed pimlico erc20 paymaster contract addresses. The structure should be as follows\n{\n    \"10\": {\n        \"USDC\": \"0x99fB8d618F52a42049776899D5c07241D344a8A4\",\n        \"DAI\": \"0x3bE5380ec8cfe159f0525d16d11E9Baba516C40c\",\n        \"USDT\": \"0x9102889001d0901b3d9123651d492e52ce772C6b\"\n    },\n    \"420\": {\n        \"LINK\": \"0x53F48579309f8dBfFE4edE921C50200861C2482a\"\n    },\n    \"421613\": {\n        \"LINK\": \"0x0a6Aa1Bd30D6954cA525315287AdeeEcbb6eFB59\"\n    }\n} which also needs to be converted into `base64` value\n- FEE_MARKUP - this is used to add fee if it gets from the provider. This needs to be inputted as a number in terms of gwei\n- ETHERSCAN_GAS_ORACLES - the list of urls for all chains. Note that the response got is in terms of etherscan API Documentation https://docs.polygonscan.com/api-endpoints/gas-tracker#get-gas-oracle\nThe structure should be as follows\n{\n  \"137\": \"https://api.polygonscan.com/api?module=gastracker\u0026action=gasoracle\u0026apikey=YourApiKeyToken\", // Note that you need to replace YourApiKeyToken to actual API key from etherscan\n  \"1\": \"https://api.etherscan.io/api?module=gastracker\u0026action=gasoracle\u0026apikey=YourApiKeyToken\"\n} which then needs to be converted into `base64` value\n- DEFAULT_API_KEY - this is used for checking token paymaster deposits. Please use an apiKey which has the list of token paymasters that needs to be monitored. Please note that it only tracks the token paymasters in `ERC20_PAYMASTERS` and `MULTI_TOKEN_PAYMASTERS` variable specified inside the apiKey.\n- WEBHOOK_URL - this is used to notify if the token paymaster deposit comes below 'thresholdValue' specified in backend/config.json and please note that each chain has configured threshold as approx. 50 USD worth of native tokens\n\n## API KEY VALIDATION\n- In ARKA Admin Frontend, create an API_KEY with the following format - \n* Min length - 8 Max length - 20\n* contains atleast one Special characters out of these - `@$!%*-_\u0026`\n* contains atleast one lowercase alphabet\n* contains atleast one uppercase alphabet\n* contains atleast one digit 0-9\n\n\n## 🔙 Arka Backend\n\nThis contains the full source code and implementation of Arka. \n\nTo run your own instance of this, please [follow these steps.](https://github.com/etherspot/arka/tree/master/backend#how-to-run)\n\nYou can see a [list of available endpoints here](https://github.com/etherspot/arka/tree/master/backend#available-endpoints--).\n\n\n### Local - Setup \n\n#### environment for backend\n\n1. Start Docker postgres database\n\n```sh\ncd local-setup\n```\n\n```sh\ndocker-compose up -d\n```\n\n- Verify if the postgres docker instance is up and running\n\n```sh\ndocker ps -a\n```\n\n```sh\ndocker logs --follow local-setup-db-1\n```\n\n- It must show up logs similar to this\n\n```\nPostgreSQL init process complete; ready for start up.\n2024-06-24 19:31:56.739 UTC [1] LOG:  starting PostgreSQL 16.1 (Debian 16.1-1.pgdg120+1) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit\n2024-06-24 19:31:56.740 UTC [1] LOG:  listening on IPv4 address \"0.0.0.0\", port 5432\n2024-06-24 19:31:56.740 UTC [1] LOG:  listening on IPv6 address \"::\", port 5432\n2024-06-24 19:31:56.741 UTC [1] LOG:  listening on Unix socket \"/var/run/postgresql/.s.PGSQL.5432\"\n2024-06-24 19:31:56.744 UTC [66] LOG:  database system was shut down at 2024-06-24 19:31:56 UTC\n2024-06-24 19:31:56.748 UTC [1] LOG:  database system is ready to accept connections\n```\n\n2. create .env\n\n```sh\ncp .env.example .env\n```\n\n3. populate these environment variables\n\n```sh\nLOG_LEVEL=\nAPI_HOST=\nAPI_PORT=\nUNSAFE_MODE=true\nSUPPORTED_NETWORKS=\nCRON_PRIVATE_KEY=\nDEFAULT_INDEXER_ENDPOINT=\nFEE_MARKUP=0\nMULTI_TOKEN_MARKUP=\nADMIN_WALLET_ADDRESS=\nETHERSCAN_GAS_ORACLES=\"\"\nDEFAULT_API_KEY=\"\"\nWEBHOOK_URL=\nHMAC_SECRET=\nDATABASE_URL=\nDATABASE_USER=\nDATABASE_PASSWORD=\nDATABASE_NAME=\nDATABASE_SCHEMA_NAME=arka\nDATABASE_SSL_ENABLED=false\nDATABASE_SSL_REJECT_UNAUTHORIZED=false\n```\n\n4. start docker instance for backend, admin_frontend, frontend\n\n```sh\ndocker-compose up --build -d\n```\n\n5. Here we need to create a network and tag backend \u0026 postgres on same network\n\n```sh\ndocker network create arka-network    \n```\n\n6. add postgres instance to docker network\n\n```sh\ndocker network connect arka-network local-setup-db-1\n```\n\n7. add arka backend docker instance to docker-network\n\n```sh\ndocker network connect arka-network arka-backend-1\n```\n\n8. restart backend docker instance\n\n```sh\ndocker-compose up -d\n```\n\n9. verify backend logs\n\n```sh\ndocker logs arka-backend-1\n```\n\n## 🖥 Arka Admin Frontend\n\nThis contains ability to change system configuration, apiKeys and apiKey-config that are available in database.\n\n## 🖥 Arka Frontend\n\nThis is a basic frontend which let's a user interact with the Arka smart contract on various chains.\n\n\n## 🔗 Important links\n\n- **[Arka developer documentation](https://etherspot.fyi/arka/intro)**\n- **[Sponsor a Transaction](https://etherspot.fyi/arka/sponsor-a-transaction)**\n- **[Chains which Arka is live on](https://etherspot.fyi/skandha/chains)**\n\n\n## 💬 Contact\n\nIf you have any questions or feedback about Arka, please feel free to reach out to us.\n\n- [Follow on Twitter](https://twitter.com/etherspot)\n- [Join our discord](https://discord.etherspot.io/)\n\n## 📄 License\n\nLicensed under the [MIT License](https://github.com/etherspot/arka/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetherspot%2Farka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fetherspot%2Farka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetherspot%2Farka/lists"}