docs(gnoconnect): add specs

[moul]

To continue the work in #3609, which unlocks the @gnolang/onbloc team to proceed with #3610, I’m proposing some initial and more formal specifications for gnoconnect.

One key improvement is enabling support for non-Gnoweb instances that wish to implement gnoconnect for a domain name different from the current one. For example, a website like example.com might include links such as https://foo.gno.land/r/bar$help&func=Baz and would need a way to declare foo.gno.land as a valid Gnoland instance.

Another extension in the spec is the proposal of an HTTP header alternative, complementing the existing HTML metadata. This ensures compatibility with static setups like GitHub Pages or IPFS, which might not support dynamic HTTP headers, while still allowing them to specify gnoconnect details.

I suggest keeping this PR open to refine and challenge these ideas while the onbloc team works on their first integration. This will give us the opportunity to iterate and improve as needed. Once this initial integration progresses, we can enhance the work on Gnoweb to fully support the latest version of these specifications.

cc @gnolang/onbloc for their work on Adena
cc @gfanton for his work on Gnobro

[Gno2D2]

🛠 PR Checks Summary

All Automated Checks passed. ✅

Manual Checks (for Reviewers):

• [ ] IGNORE the bot requirements for this PR (force green CI check)

Read More

🤖 This bot helps streamline PR reviews by verifying automated checks and providing guidance for contributors and reviewers.

✅ Automated Checks (for Contributors):

🟢 Maintainers must be able to edit this pull request (more info) 🟢 Changes to 'docs' folder must be reviewed/authored by at least one devrel and one tech-staff

☑️ Contributor Actions:

1. Fix any issues flagged by automated checks.
2. Follow the Contributor Checklist to ensure your PR is ready for review.
   • Add new tests, or document why they are unnecessary.
   • Provide clear examples/screenshots, if necessary.
   • Update documentation, if required.
   • Ensure no breaking changes, or include BREAKING CHANGE notes.
   • Link related issues/PRs, where applicable.

☑️ Reviewer Actions:

1. Complete manual checks for the PR, including the guidelines and additional checks if applicable.

📚 Resources:

• Report a bug with the bot.
• View the bot’s configuration file.

Debug

Automated Checks

Maintainers must be able to edit this pull request (more info)

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 The base branch matches this pattern: ^master$
    └── 🟢 The pull request was created from a fork (head branch repo: moul/gno)

Then

🟢 Requirement satisfied
└── 🟢 Maintainer can modify this pull request

Changes to 'docs' folder must be reviewed/authored by at least one devrel and one tech-staff

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 The base branch matches this pattern: ^master$
    └── 🟢 A changed file matches this pattern: ^docs/ (filename: docs/README.md)

Then

🟢 Requirement satisfied
└── 🟢 And
    ├── 🟢 Or
    │   ├── 🟢 Pull request author is a member of the team: tech-staff
    │   └── 🔴 At least 1 user(s) of the team tech-staff reviewed pull request(with state "APPROVED")
    └── 🟢 Or
        ├── 🔴 Pull request author is a member of the team: devrels
        └── 🟢 At least 1 user(s) of the team devrels reviewed pull request(with state "APPROVED")

Manual Checks

**IGNORE** the bot requirements for this PR (force green CI check)

If

🟢 Condition met
└── 🟢 On every pull request

Can be checked by

• Any user with comment edit permission

[moul]

FYI, I believe that CORS headers and WalletConnect (from Ethereum) are a good source of inspiration.

I also wanted to share a few details regarding clients:

• Gnoweb only implements the specification by exposing headers (partial provider).
• Contracts' Render implements the specification by exposing txlink-formatted links (partial provider).
• Adena consumes everything: the headers from Gnoweb (or other webpage) and the txlinks (full consumer).
• Gnobro won't need to parse any headers, as it considers everything it consumes to be a (local) Gno experience. Therefore, it is only a txlink consumer (partial consumer).
• Upcoming tools, such as client-side SDKs in JavaScript or Go, will likely be full consumers most of the time. They may be partial consumers when loading markdown and only wanting to support txlinks. We can also envision other server-side SDKs, like those for React or other ecosystems, to help expose HTML metadata and create custom txlinks.

[zivkovicmilos]

Pasting here for reference: https://eips.ethereum.org/EIPS/eip-1193

[aeddi]

The first two fields are easy to understand, but regarding the third one (txdomains), I'm not totally sure how it works.

I guess the idea is:

• example.com is a website that wants to allow its visitors to make a transaction on a Gno chain, but it isn't itself a Gno node, so it isn't connected to the blockchain and doesn't offer an RPC endpoint for communication.
• example.com then adds foo.gno.land to its txdomains which provides a Gno node with an RPC endpoint, so the wallet / client can send its request.

If that's the case, I have a few questions:

• Is the point of having a list of domains is to be able to fallback? Like, if we try the first domain and it doesn't work, we try the second, and so on?
• What's the purpose of the rpc field then? Will 127.0.0.1 in your example be replaced by the first domain from the txdomains list? Will the port number 26557 for the RPC endpoint be the same for all the listed domains?

Maybe I'm misunderstanding, but it seems to me that the role of these two fields overlap. In that case, why not merge the two fields like this, for example:

<meta name="gnoconnect:txdomains" content="gno.land:26657, fallback.land:1234, anotherfallback.land:4321" />
<meta name="gnoconnect:chainid" content="dev" />"

(In that case, the key name txdomains would become slightly inadequate since it's more a list of RPC endpoints (hostname + port) rather than just a list of domains.)

[moul]

Depends on #3868

[moul]

Updated the docs/ to match the new folder organization and imrpove the content. Ready for a new review. cc @gnolang/onbloc @alexiscolin @gfanton @leohhhn