GitCircles: Automating Token Rewards For GitHub Contributions

GitCircles: Revolutionizing GitHub Contributions with Automated Token Rewards

Hey everyone! Let's dive into how GitCircles is transforming the way we appreciate and reward contributors on GitHub. This article will break down the automated token reward system for merge requests (MRs), offering a clear understanding of the process, state transitions, and key considerations. We'll explore how GitCircles leverages the power of blockchain technology and Ergo wallets to fairly distribute tokens based on contributions, ensuring transparency and providing control to both repository owners and authors. It's all about making open-source collaboration even more rewarding, guys! Let's get into it.

The Heart of GitCircles: Automating Token Rewards

At the core of GitCircles is an automated system designed to reward contributors for their valuable work on merge requests (MRs). When a merge request is closed, GitCircles kicks into action, initiating a series of steps that ultimately result in the distribution of tokens. This system is built around a well-defined state machine, ensuring that every MR is processed systematically and efficiently. We'll break down each stage and its transitions, making sure you understand how this awesome system works!

Understanding the State Machine: Your Guide to GitCircles' Workflow

To grasp the inner workings of GitCircles, we need to understand its state machine. This is a visual representation of the different states an MR can be in and the transitions between them. It’s like a roadmap guiding each MR through the process, from its initial discovery to the final token distribution or cancellation. The state machine is critical for understanding how the system handles different scenarios, such as authors not having wallets or repository owners wanting to halt the reward process.

Delving into the States: A Step-by-Step Explanation

Let's break down each state to understand what happens at every stage of the process.

1. Registered State: The Starting Point

This is the default state for every merge request that GitCircles discovers. When GitCircles first detects an MR, it immediately enters the Registered state. At this stage, the system simply acknowledges the existence of the MR. Think of it as the system saying, "Hey, we see you!"

Transition: From Registered to ScheduledForSending Notification Template:

• The Merge Request has been discovered by GitCircles.
• The author's contribution will be automatically appreciated in XX days.
• Repository Owner or Merge Request Author can cancel the appreciation process. To cancel, comment GitCircles STOP APPRECIATION below.
• Leave this message to proceed with appreciation and agree with GitCircles Terms of Conditions.
• Successful appreciation requires the author to have a registered Ergo wallet.
• Register your wallet by following the instructions.
• XX: 14 days by default (configurable by repository owner in the future)

2. Scheduled for Token Sending: Ready to Go!

Once the initial notification is successfully published, the MR transitions to the ScheduledForSending state. This indicates that the system is ready to proceed with the token distribution process, pending certain conditions. It's like the MR is now on a timer, counting down to the moment when tokens might be sent.

3. Processed Without STOP: The Reward is on Its Way!

If the 14-day period expires without a STOP comment and the author has a registered wallet, the MR enters this state. This is where the magic happens: the system calculates the appreciation amount and issues a blockchain transaction to send the tokens. If everything goes smoothly, the author receives their well-deserved reward. The system then publishes a success notification, and the MR moves to a completed state.

Process:

1. Sync author's Ergo wallet address from GitHub account.
2. Calculate appreciation amount (XX): Total tokens = Lines added + Lines removed.
3. Issue a blockchain transaction for the calculated amount.
4. Publish success notification:

• GitCircles has successfully sent appreciation of (XX tokens) to Author for this merge request.
• Transaction details: View on Blockchain Explorer.

5. Move to completed state after transaction publication.

4. Appreciation Stopped: Halting the Process

If a STOP comment is detected during daily monitoring, the system enters this state. This allows the repository owner or the author to halt the token distribution process. The system then publishes a cancellation message, informing everyone that the appreciation will not be sent. It's a safety mechanism to ensure control and flexibility.

Trigger: STOP comment detected during daily monitoring. Action: Publish cancellation message:

• GitCircles will not send appreciation of (XX tokens) for this merge request due to manual interruption by UserWhoInterrupted.

Final state after message publication

5. Waiting for Wallet Registration: The Author's Turn

If the 14-day period passes without a STOP comment but the author doesn't have a registered wallet, the MR enters this state. The system will then send a notification, informing the author that appreciation will be sent automatically once a wallet is detected. It's a reminder for the author to register their wallet and claim their reward.

Trigger: 14 days pass with no STOP comment but author has no registered wallet Action: Publish notification:

• GitCircles cannot send appreciation of (XX tokens) because Author has no registered Ergo wallet.
• Appreciation will be sent automatically when a wallet is detected.
• Author can cancel future attempts by commenting GitCircles STOP APPRECIATION.

Monitoring: GitCircles continuously checks author's profile for wallet registration.

6. Stopped by Author Cancellation: Request Acknowledged

If an author, who doesn't have a wallet, explicitly cancels via a STOP comment, the MR enters this state. The system acknowledges the cancellation and confirms that no further attempts will be made to send appreciation. It's all about giving the author control over their participation.

Trigger: Author without wallet explicitly cancels via STOP comment Action: Publish acknowledgement message:

• GitCircles has acknowledged the cancellation request from Author.
• No further appreciation attempts will be made for this merge request.

Final state with no further action

Testing and Key Implementation Considerations: Ensuring a Smooth Operation

To ensure that everything functions as intended, thorough testing is essential. This involves setting up a dedicated test token on a test blockchain and establishing a secure connection to an Ergo testnet node. Secure storage for API keys, wallet addresses, and transaction credentials is also a must. Furthermore, a mock environment with simulated GitHub webhooks is necessary for comprehensive testing.

Diving Deeper: Security, Error Handling, and Rate Limiting

When implementing this system, several key considerations are very important. Security is paramount, with all blockchain interactions requiring encrypted communications. Robust error handling is crucial for dealing with potential wallet detection failures. Comprehensive logging provides audit trails for debugging and transparency, and rate limiting is essential for GitHub API calls to prevent abuse.

Conclusion: Rewarding Contributions with Transparency

In conclusion, the automated token system provides a fair and transparent way to reward contributors. It's a system designed to encourage engagement and show appreciation for the hard work of developers. By incorporating the STOP mechanism and ensuring author consent through wallet registration, GitCircles empowers both repository owners and authors. This helps foster a collaborative environment, driving innovation and growth in the open-source community.

For more information, check out the Ergo Platform website!