{"id":23181681,"url":"https://github.com/raid-guild/wpokt-oracle","last_synced_at":"2025-04-05T03:16:10.256Z","repository":{"id":236297235,"uuid":"792327666","full_name":"raid-guild/wpokt-oracle","owner":"raid-guild","description":"Validator network for the wpokt bridge from the shannon upgrade of the pocket network to ethereum","archived":false,"fork":false,"pushed_at":"2024-07-03T11:46:38.000Z","size":1159,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":11,"default_branch":"dev","last_synced_at":"2025-02-10T11:21:42.976Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/raid-guild.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2024-04-26T12:50:03.000Z","updated_at":"2024-07-03T11:46:41.000Z","dependencies_parsed_at":"2024-04-26T13:51:21.202Z","dependency_job_id":"5339ff42-9027-4dea-aa5d-37bf1783f951","html_url":"https://github.com/raid-guild/wpokt-oracle","commit_stats":null,"previous_names":["raid-guild/wpokt-validator-network","raid-guild/wpokt-oracle"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raid-guild%2Fwpokt-oracle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raid-guild%2Fwpokt-oracle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raid-guild%2Fwpokt-oracle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raid-guild%2Fwpokt-oracle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raid-guild","download_url":"https://codeload.github.com/raid-guild/wpokt-oracle/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280255,"owners_count":20912967,"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":[],"created_at":"2024-12-18T08:17:27.247Z","updated_at":"2025-04-05T03:16:10.238Z","avatar_url":"https://github.com/raid-guild.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wPOKT Oracle\n\nThe wPOKT Oracle is a validator node that facilitates the bridging of POKT tokens from the Shannon upgrade of the POKT network to wPOKT on the Ethereum Mainnet and other EVM networks.\n\n## How It Works\n\nThe wPOKT Oracle consists of three parallel services for each network that enable the bridging of POKT tokens. Each service operates on an interval specified in the configuration. Here's an overview of their roles:\n\n1. **Message Monitor:**\n   Monitors the network for new transactions and creates a message in the database after confirming them.\n\n2. **Message Signer:**\n   Validates pending messages and signs them. For the Cosmos network, it broadcasts the messages. For EVM networks, users are responsible for broadcasting the signed messages themselves.\n\n3. **Message Relayer:**\n   Monitors the network for confirmed Cosmos transactions and fulfilled message orders on supported EVM networks. It ensures these transactions are confirmed on the respective networks.\n\nAdditionally, the Oracle includes a health service that periodically reports the status of the Golang service and sub-services to the database.\n\nThrough these services, the wPOKT Oracle bridges POKT tokens to wPOKT, providing a secure and efficient validation process for the entire ecosystem.\n\n## Installation\n\nNo specific installation steps are required. Ensure you have Golang installed locally and access to a MongoDB instance, either locally or remotely.\n\n## Usage\n\nTo run the wPOKT Oracle, execute the following command:\n\n```bash\ngo run .\n```\n\n### Configuration\n\nThe wPOKT Oracle can be configured in the following ways:\n\n1. **Using a YAML File:**\n   - A sample configuration file `config.sample.yml` is provided.\n   - Specify the config file using the `--yaml` flag:\n\n    ```bash\n    go run . --yaml config.yml\n    ```\n\n2. **Using an Env File:**\n   - A sample environment file `sample.env` is provided.\n   - Specify the env file using the `--env` flag:\n\n    ```bash\n    go run . --env .env\n    ```\n\n3. **Using Environment Variables:**\n   - Set the required environment variables directly in your terminal:\n\n    ```bash\n    SIGNER_MNEMONIC=\"your_mnemonic\" MONGODB_URI=\"your_mongodb_uri\" ... go run .\n    ```\n\nIf both a config file and an env file are provided, the config file will be loaded first, followed by the env file. Non-empty values from the env file or provided through environment variables will take precedence over the corresponding values from the config file.\n\n### Makefile\n\n- **Run using:**\n\n    ```bash\n    make dev\n    ```\n\n- **Build using:**\n\n    ```bash\n    make build\n    ```\n\n- **Build Docker image using:**\n\n    ```bash\n    make docker_build\n    ```\n\n## Valid Memo\n\nThe validator node requires transactions on the POKT network to include a valid memo in the format of a JSON string. The memo should have the following structure:\n\n```json\n{ \"address\": \"0xC9F2D9adfa6C24ce0D5a999F2BA3c6b06E36F75E\", \"chain_id\": \"1\" }\n```\n\n- `address`: The recipient address on the Ethereum network.\n- `chain_id`: The chain ID of the Ethereum network (represented as a string).\n\nTransactions with memos not conforming to this format will not be processed by the validator.\n\n## Docker Image\n\nThe wPOKT Oracle is also available as a Docker image hosted on [Docker Hub](https://hub.docker.com/r/dan13ram/wpokt-oracle). You can run the validator in a Docker container using the following command:\n\n```bash\ndocker run -d --env-file .env docker.io/dan13ram/wpokt-oracle:latest\n```\n\nEnsure you have set the required environment variables in the `.env` file or directly in the command above.\n\n## Unit Tests\n\nTo assess the individual components of the wPOKT Oracle, follow these steps:\n\n1. **Execute Unit Tests:**\n    - Open your terminal and run the unit tests using the command:\n\n        ```shell\n        make test\n        ```\n\n2. **Check Coverage:**\n    - To check the test coverage of the codebase, use the following command:\n\n        ```shell\n        make test_coverage\n        ```\n\n## End-to-End Tests\n\nTo test the core functionalities of the wPOKT Oracle in a controlled environment, follow these steps:\n\n1. **Clone the poktroll Repository:**\n    - Open your terminal and clone the `poktroll` repository from GitHub:\n\n    ```bash\n    git clone https://github.com/pokt-network/poktroll\n    cd poktroll\n    make localnet_up\n    ```\n\n    - Follow instructions at [poktroll quickstart](https://dev.poktroll.com/develop/developer_guide/quickstart) for more details on running the poktroll network locally.\n    - Allow up to 5 minutes for the local network to be fully operational.\n\n2. **Start Local Network:**\n    - Move to your project folder and execute the following commands to set up the local network for our oracle and Ethereum networks:\n\n        ```bash\n        make clean\n        make localnet_up\n        ```\n\n    - Please allow up to 5 minutes for the local network to be fully operational.\n\n3. **Run Tests:**\n    - Once the local network is ready, initiate the end-to-end tests using the command:\n\n        ```bash\n        make e2e_test\n        ```\n\n    - Ensure you have Node.js v18 installed to run the tests.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraid-guild%2Fwpokt-oracle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraid-guild%2Fwpokt-oracle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraid-guild%2Fwpokt-oracle/lists"}