# Github definition / scoping

## Ressources

The oracle, comprising certain contracts and an external bot, aims to translate select GitHub metrics onto the chain, rendering them usable in our on-chain ecosystem.

While I've shared my skepticism about GitHub being the sole platform for evaluations and score/token allocations, I remain steadfast in treating GitHub as a reliable data source. It's essential we maintain its widely recognized URIs for consistency.

Elaborating further:

On-Chain Reflection of Issues and PRs: I propose that we mirror essential data from GitHub, such as titles, statuses (open, closed, merged), URIs, and some metadata. Visualize it like this:
import "gno.land/r/github"

issue := github.IssueByID("gnolang/gno#4242")
println(issue.Title, issue.State)

This allows on-chain management and tracking that's interlinked with GitHub issues. As @waymobetta and @MichaelFrazzy have been exploring similar territory, I'd like to emphasize:
- We shouldn't treat GitHub activities as direct equivalents to scores. While these metrics can guide score determinations, human oversight is vital to ensure fairness and counteract potential manipulation.
- The focus shouldn't be restricted to "merged PRs." Open issues, valuable but closed PRs, and other meaningful contributions deserve recognition.

Two-Way Data Flow: While our bot can translate GitHub activities on-chain, the opposite should be feasible too. It can monitor on-chain events and mirror these as comments on GitHub issues and PRs.

GitHub and Gno Account Linkage: As discussed, users can create a repository like github.com/<username>/.gno with a config.yml, signed with their private key. An on-chain transaction like:

`gnokey maketx gno.land/r/github -func LinkAccount -args moul -args sig(moul)`

can create a robust two-way connection, broadening our interaction possibilities, such as a bot commenting on GitHub issues/PRs.

## Proposal 1

1. **Repository Creation**
- Users will create a dedicated repository on GitHub with the following format: `github.com/<username>/.gno`
- Inside this repository, users will place a `config.yml` file containing necessary information and sign it with their private key.
example:

    
        functions: LinkAccount
        signatures: xxx
        public_key: xxxx
    

2. **User Interaction**
- When a user wants to interact with the Oracle, they can:
- **GitHub**: Comment on a Gno-related issue in the gno project.
- **Discord**: Send a specific message format in a designated Discord channel.

3. **Server Validation**
- The Gno server will monitor these interactions thenIt will parse the comments on Gno-related issues, extracting the signed `config.yml` file.
- The server will then:
- Verify the signature on the `config.yml` file to ensure authenticity.
- Validate the content of the `config.yml` for required fields and format.

4. **Data Push to Chain**
- Upon successful validation:
- The function will be excuted onto the Gno Realm.

Cons: Gno will pay the gas

sequenceDiagram
    User ->> Server: Ask github verification
    Server ->> Github: Get user gno/config.yaml
    Server ->> Server: Parse to get user address
    Server ->> Oracle: Push address, githubId

## Proposal 2

1. **Repository Creation**
- Users will create a dedicated repository on GitHub with the following format: `github.com/<username>/.gno`
- Inside this repository, users will place a `config.yml` file containing necessary information and sign it with their private key.
- Example `config.yml`:

       functions: LinkAccount
       signatures: xxx
       public_key: xxxx

2. **User Interface**
- When a user wants to interact with the Oracle, they can:
- Request the server to verify their repository and ask signature.
- Provide the necessary information such as repository URL, signed `config.yml`, and desired action.
3. **Server Validation**
- The Gno server will parse the request and validate the repository:
- It will check the provided repository URL and fetch the signed `config.yml` file.
- Verify the signature on the `config.yml` file to ensure authenticity.
- Validate the content of the `config.yml` for required fields and format.
- If the validation is successful, the server will generate a unique signature for the requested function and argument.
4. **User Interaction with the Oracle**
- The server will respond to the user with the signed function and argument, ready for execution on the Gno Realm.

- The user can then execute this function on the Gno Realm with the provided signature.
5. **Oracle**
- Upon receiving the signed function and argument from the user:
- The Gno Realm will verify the provided signature to ensure the request's authenticity.

Cons: user will pay the gas

sequenceDiagram
    Server ->> Realm: Add Public Key
    User ->> Server: Ask github verification
    Server ->> Github: Get user gno/config.yaml
    Server ->> Server: Parse to get user address
    Server ->> User: Signature(address,githubID)
    User ->> Realm: Push address,githubID, serverSignature

## Some sequence diagram for other flows

###

sequenceDiagram
    User ->> Github: Comment on github
    Github ->> Bot: User Comment
    Bot ->> Github: Get user gno/config.yaml
    Bot ->> Bot: Parse to get user address
    Bot ->> Oracle: Push adress, githubId, data related to the comment 

## Exploration