Skip to content
This repository was archived by the owner on Oct 1, 2025. It is now read-only.

Commit a936a0a

Browse files
justussohjustussoh
authored
feat: added documentation for setting up GSN (#59)
* feat: added documentation for setting up GSN * feat: rearrange documentation to users * fix: added glossary * feat: updated content * fix: pr comments * fix: custom relay provider * fix: ranme errror * fix: Delete Creating-a-custom-relay-provider * fix: missing links * fix: merge error
1 parent ccd5960 commit a936a0a

File tree

9 files changed

+257
-2
lines changed

9 files changed

+257
-2
lines changed

‎website/docs/advanced/gsn/creating-a-custom-relay-provider.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
id: creating-a-custom-relay-provider
3+
title: Creating a Custom RelayProvider
4+
sidebar_label: Creating a Custom RelayProvider
5+
---
6+
7+
A [RelayProviders](https://docs.opengsn.org/learn/index.html#client) allows a client to send signed transaction to the blockchain.
8+
9+
We provided our own [implementation](https://github.com/TradeTrust/document-creator-website/pull/76/files#diff-ae839d6f834102d8aaabb1f74fe1acb14ca32a3bee209ed2264f846fcca2679aR15) and you can do your own by following this [guide](https://docs.opengsn.org/tutorials/integration.html#the_user_interface_code).
10+
11+
### Gsn Capable Interface
12+
13+
As not every contract can accept relayed transactions, we have provided a new Erc165 interface `GsnCapable` to test if the contract can accept relayed transactions. Additionally, the inherited interface can return the corresponding paymaster address paying for the transaction.
14+
15+
To test if the given contract is `GsnCapable` we can make use of the method `supportsInterface` with the `interface-id` of [`0xa5a23640`](https://github.com/Open-Attestation/document-store/blob/master/contracts/GsnCapable.sol#L10) on any smart contract (the `interface-id` is our own implementation). If the contract supports the interface, we can assume that it can handle relayed transactions.
16+
17+
## Additional Resource
18+
19+
Below is a list of additional resources for more information:
20+
21+
- [OpenGSN](https://docs.opengsn.org/learn/index.html)

‎website/docs/advanced/gsn/gas-station-network.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
id: gas-station-network
3+
title: What is GSN?
4+
sidebar_label: What is GSN?
5+
---
6+
7+
Anyone who sends an Ethereum transaction needs to have ETH to pay for gas fees. This forces new users to pass [KYC (Know Your Customer)](../../appendix/glossary#know-your-customer-kyc) and purchase ETH before they can start using any [Decentralized Application (dapp)](../../appendix/glossary#decentralized-application-dapp). This can be a major hurdle for users without prior crypto experience that are unfamiliar with the concept of needing to keep ETH in their wallet for gas.
8+
9+
Ethereum Gas Station Network (GSN) abstracts away gas to minimize onboarding & UX friction for dapps. With GSN, clients with no Ethereum can interact with Ethereum contracts without them having to pay for gas fees.
10+
11+
This guide targets developers who have Ethereum and wish to sponsor their users in making transactions to a given contract.
12+
13+
## How does it work?
14+
15+
![GSN Flow](/docs/advanced/gas-station-network/gsn_flow_full_layered.jpg)
16+
17+
_Source: [Open GSN](https://docs.opengsn.org/learn/index.html)_
18+
19+
Instead of signing an Ethereum transaction, which would require ETH for gas, a user signs a message containing information about a transaction they would like to execute and sends it to a relay server. Before the relay server pays, it verifies that it will get refunded by a Paymaster contract.
20+
21+
A [Paymaster](https://docs.opengsn.org/learn/index.html#paymaster) holds ETH and can implement any business logic to decide whether to accept or reject a meta transaction. For example, accepting only transactions by whitelisted users, or to the contracts methods required for onboarding users, or only transactions that include a repayment in tokens to the Paymaster, etc.
22+
23+
Assuming that the Paymaster is willing to pay for transaction, the transaction gets forwarded to our contract, executing the function logic of issue, revocation, minting etc.
24+
25+
## Initial idea
26+
27+
Given a service provided, we wanted a way for the provider to pay for the transaction (this means that clients would not need to own any Ethereum to interact with the Smart Contract). For example, GovTech could be holding on to a Paymaster while subsidiaries are only required to have a empty wallet address to interact with GovTech's Smart Contracts.
28+
29+
## Next steps
30+
31+
Now that we understand how GSN can be helpful as developers and how they work, we can move on to deploying the [Paymaster](/docs/advanced/gsn/setup-paymaster) and creating a [GsnCapableDocumentStore](/docs/advanced/gsn/gsn-capable-document-store).
32+
33+
## Additional Resource
34+
35+
Below is a list of additional resources for more information:
36+
37+
- [OpenGSN](https://docs.opengsn.org/learn/index.html)

‎website/docs/advanced/gsn/gsn-capable-document-store.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
id: gsn-capable-document-store
3+
title: Deploying a GsnCapableDocumentStore
4+
sidebar_label: Deploy GsnCapableDocumentStore
5+
---
6+
7+
The GsnCapableDocumentStore is a variant of Document Store which allows for relayed transactions. The rest of the functionality mimics that of Document Store.
8+
9+
This guide is for developers who have Ethereum and want to set up a document store that accept gsn relayed transactions for their users.
10+
11+
## Pre-requisite
12+
13+
- [OpenAttestation CLI](/docs/component/open-attestation-cli) installed
14+
- [Ethereum wallet with sufficient ethers](/docs/verifiable-document/wallet)
15+
16+
> We will only show example for the wallet and one must change the command accordingly if using another methodwallet)
17+
18+
## Deploying via OpenAttestation CLI
19+
20+
You will also need the corresponding address of the [Trust Forwarder](https://docs.opengsn.org/learn/index.html#forwarder) for your network provided by GSN. You can find the most updated list [here](https://docs.opengsn.org/gsn-provider/networks.html) or the highlighted below.
21+
22+
![GSN Networks](/docs/advanced/gas-station-network/gsn_network_address.png)
23+
24+
To deploy a GsnCapableDocumentStore you can do so by using the following command. You may replace the `<document-store-name>` with a suitable name (the name does not matter).
25+
26+
```bash
27+
open-attestation deploy gsn-capable-document-store "My Name" 0x25CEd1955423BA34332Ec1B60154967750a0297D --network ropsten
28+
```
29+
30+
> `0x25CEd1955423BA34332Ec1B60154967750a0297D` is the address of trust forwarder for ropsten provided by GSN
31+
32+
This will deploy the GsnCapableDocumentStore on the `ropsten` network. You should see a similar output when the deployment is successful:
33+
34+
```bash
35+
… awaiting Waiting for transaction 0xf4a222c9bcc31ebd202a110568a7798218477482b773f49290e1df8b4936a313 to be mined
36+
✔ success Gsn Capable document store deployed at 0x0d3dFdd82FF13Ff06a336e28CABE465B64fD8168
37+
```
38+
39+
> Save YOUR gsn capable document store address for future reference
40+
41+
After successfully deploying the GsnCapableDocumentStore, you will need to set the paymaster address. This will allow relayers to know which paymaster to request payment from. You can do so with the following command.
42+
43+
```bash
44+
open-attestation gsn-capable set-paymaster --network ropsten --gsn-capable-address 0x0d3dFdd82FF13Ff06a336e28CABE465B64fD8168 --paymaster-address 0xcB94584760bCA09e9fa7117C4eE966814f17a306
45+
```
46+
47+
> This allows our client to look up the paymaster address for your contract without additional declaration.
48+
49+
### DNS Configuration
50+
51+
Similar to [binding the document store to a domain name](../../verifiable-document/document-store), you will have to bind the identity of the GSN capable document store to a domain name.
52+
53+
If you like more detailed setup instructions, you may refer to the [documentation for configuring DNS](../configuring-dns/).
54+
55+
> Take note of the domain you are inserting the records on, you will need this later
56+
57+
## Additional Resource
58+
59+
Below is a list of additional resources for more information:
60+
61+
- [OpenGSN](https://docs.opengsn.org/learn/index.html)
62+
- [GsnCapableDocumentStore](https://github.com/Open-Attestation/document-store/blob/master/contracts/GsnCapableDocumentStore.sol)

‎website/docs/advanced/gsn/setup-paymaster.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
id: setup-paymaster
3+
title: Creating a Paymaster
4+
sidebar_label: Creating a Paymaster
5+
---
6+
7+
A [Paymaster](https://docs.opengsn.org/learn/index.html#paymaster) holds ETH and can implement any business logic to decide whether to accept or reject a meta transaction. For example, accepting only transactions by whitelisted users, or to the contracts methods required for onboarding users, or only transactions that include a repayment in tokens to the Paymaster, etc.
8+
9+
A Paymaster is useful for any party willing to pay for a relayed transaction to a given address using the GSN network.
10+
11+
This guide is for developers who want to setup a paymaster wallet to sponsor all transactions to a given smart contract.
12+
13+
## Implementation of Paymaster
14+
15+
We provided an implementation of the Paymaster which allows for multiple payable address.
16+
17+
You can refer to the source code of our Paymaster [here](https://github.com/Open-Attestation/document-store/blob/master/contracts/NaivePaymaster.sol).
18+
19+
## Deploying Paymaster
20+
21+
### Pre-requisite
22+
23+
- [OpenAttestation CLI](/docs/component/open-attestation-cli) installed
24+
- [Ethereum wallet with sufficient ethers](/docs/verifiable-document/wallet)
25+
26+
> We will only show example for the wallet and one must change the command accordingly if using another method
27+
28+
### Deploying via OpenAttestation CLI
29+
30+
Simply run the following command. You may replace the `<paymaster-name>` with a suitable name (the name does not matter).
31+
32+
```bash
33+
open-attestation deploy paymaster "My Paymaster" --network ropsten --encrypted-wallet-path wallet.json
34+
```
35+
36+
This will deploy the paymaster on the `ropsten` network. You should see a similar output when the deployment is successful:
37+
38+
```bash
39+
ℹ info Deploying paymaster My Paymaster
40+
? Wallet password [hidden]
41+
… awaiting Decrypting Wallet [====================] [100/100%]
42+
ℹ info Wallet successfully decrypted
43+
...
44+
… awaiting Waiting for transaction 0xf4a222c9bcc31ebd202a110568a7798218477482b773f49290e1df8b4936a313 to be mined
45+
✔ success Paymaster My Name deployed at 0xC234Fb1F1ef0ABCD1faC90ad12F4DfC97D583F95
46+
```
47+
48+
> Save YOUR paymaster address for future reference
49+
50+
After deploying your paymaster, you will need to fund it so that the paymaster will be able to pay for relayed transactions made. We can use this command to transfer 1 ETH to the paymaster for now. Replace `<paymaster-address>` with your own paymaster's address and `<value>` with the amount you want to send.
51+
52+
```bash
53+
npx @ethersproject/cli --account wallet.json --network ropsten send 0xC234Fb1F1ef0ABCD1faC90ad12F4DfC97D583F95 1
54+
```
55+
56+
> There will be no prompting to key in you password, just key it in after command finishes loading
57+
58+
You can read more about `ethers-cli` [here](https://docs.ethers.io/v5/cli/ethers/#sandbox-utility--help).
59+
60+
## Paymaster Configuration
61+
62+
The paymaster is ready. You have to wait for clients to deploy their gsn capable document store before proceeding further.
63+
64+
In order to authorize your paymaster to pay for your contract we will need to configure the paymaster deployed earlier. We can use the `add-target` method to do so. You need to replace `<paymaster-address>` with your own paymaster and `<target-address>` with the address off the contract you intend to allow payment for.
65+
66+
```bash
67+
open-attestation paymaster add-target --network ropsten --target-address 0x9Eb76E132fCA96779A5225419352Fb1B3B5Fd706 --paymaster-address 0xcB94584760bCA09e9fa7117C4eE966814f17a306 --encrypted-wallet-path wallet.json
68+
```
69+
70+
You should see a similar output if the call is successful:
71+
72+
```bash
73+
✔ success Contract with address 0x9Eb76E132fCA96779A5225419352Fb1B3B5Fd706 has been registered on paymaster 0xcB94584760bCA09e9fa7117C4eE966814f17a306
74+
```
75+
76+
You can check if a contract is supported by the paymaster by using the following command:
77+
78+
```bash
79+
open-attestation paymaster supports-contract --network ropsten --target-address 0x9Eb76E132fCA96779A5225419352Fb1B3B5Fd706 --paymaster-address 0xcB94584760bCA09e9fa7117C4eE966814f17a306
80+
```
81+
82+
## Additional Resource
83+
84+
Below is a list of additional resources for more information:
85+
86+
- [OpenGSN](https://docs.opengsn.org/learn/index.html)
87+
- [Paymaster](https://docs.opengsn.org/learn/index.html#paymaster)
88+
- [OA-CLI Paymaster Methods](https://github.com/Open-Attestation/open-attestation-cli/#paymaster)

‎website/docs/appendix/glossary.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,11 @@ A document store is a smart contract on the Ethereum network that records the is
3838
- revoke an existing OA document
3939
- check for the validity of an OA document
4040
- transferring the document store to another owner
41+
42+
### Know Your Customer (KYC)
43+
44+
The know your customer or know your client (KYC) guidelines in financial services requires that professionals make an effort to verify the identity, suitability, and risks involved with maintaining a business relationship.
45+
46+
### Decentralized Application (dapp)
47+
48+
A DApp has its backend code running on a decentralized peer-to-peer network. Contrast this with an app where the backend code is running on centralized servers.

‎website/package-lock.json‎

Lines changed: 31 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎website/sidebars.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,16 @@
5555
"advanced/verification-methods",
5656
"advanced/identity-proofs",
5757
"advanced/custom-renderer",
58+
{
59+
"label": "Gas Station network",
60+
"type": "category",
61+
"items": [
62+
"advanced/gsn/gas-station-network",
63+
"advanced/gsn/setup-paymaster",
64+
"advanced/gsn/gsn-capable-document-store",
65+
"advanced/gsn/creating-a-custom-relay-provider"
66+
]
67+
},
5868
"advanced/configuring-dns"
5969
],
6070
"Appendix": [

‎website/static/docs/advanced/gas-station-network/gsn_flow_full_layered.jpg‎

147 KB
Loading

‎website/static/docs/advanced/gas-station-network/gsn_network_address.png‎

566 KB
Loading

0 commit comments

Comments
 (0)