Documentation update

docs/src/library.md

@@ -2,13 +2,13 @@
 
 ## Getting started
 
-To enhance the user experience, we have developed two SDKs (for now) to integrate into your web applications. They will facilitate easy interaction with the Gas Station. Currently, we have developed an SDK for Typescript and another one for Unity.
+We propose two SDKs (in TypeScript and in Unity) to use the Gas Station from your applications.
 
 ### Typescript
 
 #### Installation
 
-To install the Typescript SDK, run :
+To install the Typescript SDK in your project, run:
 
 ```bash
 npm install --save @marigold-dev/gas-station-lib
@@ -36,10 +36,11 @@ export type Operation = {
 ```
 This method then prepares the HTTP request and sends it to the `/operation` endpoint of the API, which processes the operation.
 
-- `postOperations` also takes a `sender` and an array of `Operation`, allowing you to send multiple operations at once.
+- `postOperations` also takes a `sender` and an array of `Operation`, allowing you to send multiple
+  operations at once. These operations will be treated atomically by the API: if the simulation of
+  one operation fails, then they are all discarded.
 
-
-The `PermitContract` class allows the generation of a permit [TZIP-17](https://tzip.tezosagora.org/proposal/tzip-17) for a given contract.
+The `PermitContract` class allows the generation of a off-chain permit [TZIP-17](https://tzip.tezosagora.org/proposal/tzip-17) for a contract implementing TZIP-17.
 
 > A permit is an authorization to call a specific endpoint of a smart contract with a specified parameter on behalf of a given address. This authorization may have an expiration. It is particularly useful for handling FA tokens when the user has ownership (transfer, update_operation, approve).
 
@@ -52,28 +53,28 @@ This class has two methods:
 }
 ```
 
-After calling `generatePermit`, you need to have the token owner sign the bytes to finalize the permit.
+After calling `generatePermit`, you need to ask the token owner for their signature.
 
-- `permitCall` allows calling the `permit` entrypoint on the target contract. This registers the permit in the contract storage (refer to [TZIP-17](https://tzip.tezosagora.org/proposal/tzip-17)). This method takes an object of type:
+- `permitCall` generates the permit operation using the `permit` entrypoint on the target contract. This method takes an object of type:
 ```ts
 type PermitOperation = {
   publicKey: string;
   signature: string;
   transferHash: string;
 };
 ```
-and returns an operation of type `TransferParams`.
+and returns an operation of type `TransferParams`, which can be sent using the GasStation class.
 
 #### Usage
 
-To begin, you need to import and initialize the `GasStation` object from the SDK:
+First import and initialize the `GasStation` object from the SDK:
 ```ts
 import { GasStation } from '@marigold-dev/gas-station-lib'
 
 const gasApi = new GasStation()
 ```
 
-ℹ️ NOTE: By default, the Gas Station used by the SDK is on Ghostnet but you can also provide a `apiURL` like:
+ℹ️ NOTE: By default, the Gas Station used by the SDK is the Marigold one on Ghostnet but you can also provide a `apiURL` like:
 ```ts
 import { GasStation, GAS_STATION_PUBLIC_API_GHOSTNET} from '@marigold-dev/gas-station-lib'
 
@@ -102,4 +103,4 @@ const response = await gasApi.postOperation(userAddress, {
 
 ### Unity
 
-🚧 Work in Progress 🚧
+🚧 Work in Progress 🚧

docs/src/tutorial.md

@@ -1,6 +1,6 @@
 # Tutorial
 
-To understand the potential and how to use the Gas Station, let's walk through the simple example of NFTs available at this [address](https://ghostnet.gas-station-nft-example.marigold.dev).
+This chapter walks through a simple example of a dapp using the Gas Station. You can [try it online at this address](https://ghostnet.gas-station-nft-example.marigold.dev).
 
 ## Template
 
@@ -21,13 +21,19 @@ npm run dev
 
 The files of interest are located in `src/lib`. You will find Svelte components and a `tezos.ts` file that contains utility functions such as wallet connection, etc.
 
-We will writing some pieces of code in `src/lib/MintingComponent.svelte` and `src/lib/StakingComponent.svelte`.
+To distinguish between a simple call to the Gas Station and a more complex examples involving permits, we develop two distinct components, `src/lib/MintingComponent.svelte` and `src/lib/StakingComponent.svelte`.
 Let's go ! 💪
 
-## Minting
+## Minting an NFT
 
 We'll start with minting an NFT by a user. The contract we'll use is available at this address on Ghostnet: [`KT199yuNkHQKpy331A6fvWJtQ1uan9uya2jx`](https://ghostnet.tzkt.io/KT199yuNkHQKpy331A6fvWJtQ1uan9uya2jx/operations).
-The goal here is for the user to initiate the mint action and retrieve their NFT without having to pay gas fees. For this, we will use the TypeScript SDK, and you can find more information [here](./library.md).
+This contract has an admin, which is the only account allowed to mint NFTs. This is the same
+settings as you would have in a video game, where the game decides when to mint an NFT for a user.
+In this case, the contract admin has been set to be the Gas Station account, because the `mint`
+entrypoint is always going to be called by the Gas Station.
+
+The goal here is for the user to initiate the mint action and retrieve their NFT without having to
+pay gas fees. For this, we will use the [TypeScript SDK](./library.md).
 
 First, we'll setup the GasStation SDK as follows:
 ```ts
@@ -56,9 +62,9 @@ const mintOperation = await contract.methodsObject.mint_token([{
 
 Using Taquito, we forge a transfer operation on the `mint_token` entrypoint.
 The parameters for this entrypoint are:
-- `owner` : the future owner of the NFT
-- `token_id` : l'ID of the token (NFT) that we are going to mint
-- `amount_` : the quantity of tokens we want to mint.
+- `owner`: the future owner of the NFT
+- `token_id`: ID of the token that we are going to mint
+- `amount_`: the quantity of tokens we want to mint.
 
 Finally, once the operation is forged, we can send it to the Gas Station API:
 ```ts
@@ -72,9 +78,15 @@ The operation will take a few seconds to be processed by the Gas Station (usuall
 If an error occurs (insufficient funds, authorization issue for minting the NFT, etc.), an error code will be returned, which you can handle in your dApp to inform the user.
 
 
-## Staking
+## Staking an NFT
+
+Minting NFTs from a single address is a simple enough example to start. However, a complete
+application would typically offer the possibility for the users to transfer or sell their NFTs. As
+final users do not have tez in their wallet, all the transactions are posted by the Gas Station.
 
-For staking, we need a permit. Staking involves transferring our freshly minted NFT to the contract. As we own the NFT, it is appropriate to sign a permit (authorization) to perform this transfer.
+Despite this centralization, it is still possible to maintain security and non-custodiality using
+permits. In this section, we call _staking_ the operation of sending an NFT to a contract. As the
+user ownsthe NFT, it is appropriate to sign a permit (authorization) to perform this transfer.
 
 To facilitate the development of this new feature, we will also use the TypeScript SDK (for reference, you have all the information [here](./library.md))
 
@@ -147,7 +159,7 @@ const stakingOperation = await stakingContract.methods.stake(
         userAddress
       ).toTransferParams();
 ```
-ℹ️ `PUBLIC_STAKING_CONTRACT` is an environment variable containing the contract's address implementing the staking contract.
+ℹ️ `PUBLIC_STAKING_CONTRACT` is an environment variable containing the staking contract's address.
 
 All that remains is to send the operation to the Gas Station to have the gas fees covered:
 
@@ -165,13 +177,16 @@ const response = await gasStationApi.postOperations(userAddress,
           ]);
 ```
 
-Here, we use `postOperations` to submit a batch of operations. This batch contains the operation to register the permit and the staking operation. When calling the staking contract's `stake` entrypoint, the permit will be revealed and consumed.
+Here, we use `postOperations` to submit a batch of operations. This batch contains the operation to
+register the permit and the staking operation. When calling the staking contract's `stake`
+entrypoint, the permit will be revealed and consumed.
 
 Similar to the minting operation, the Gas Station will respond in a few tens of seconds.
 
 ## Conclusion
 
-We have some pieces of code allowing a user without any XTZ to mint an NFT and stake it on the contract. This is possible thanks to the Gas Station, which relays the transaction by paying the fees.
-
+This simple example shows how a user without any tez can mint an NFT and transfer it to another
+contract in a secure way. This is possible thanks to the Gas Station, which relays the transaction
+by paying the fees.
 
-Feel free to send us your feedback and comments on this tutorial. 😃
+Feel free to send us your feedback and comments on this tutorial. 😃

docs/src/webapp.md

@@ -1,6 +1,10 @@
 # Gas Station Webapp
 
-To enhance the user experience with the Gas Station, particularly in interacting with contracts and managing the budget for fee payments, we have developed a web app, available [here](https://ghostnet.gas-station.marigold.dev/).
+The Gas Station webapp allows developers to manage sponsored contracts and operations as well as
+their budget. It also allows to express basic conditions on the spending of credits, for instance by
+giving a maximum budget per day.
+
+The webapp is hosted by Marigold: [Gas Station webapp on Ghostnet](https://ghostnet.gas-station.marigold.dev/).
 
 ⚠️ Note: currently available only on Ghostnet ⚠️
 
@@ -14,28 +18,29 @@ Like all dApps, one of the first things to do is connect your wallet by clicking
 
 ### Your contracts
 
-On the homepage, you can find all your contracts registered on the Gas Station along with their activated entrypoints.
+The homepage lists all the contracts registered in the Gas Station as well as their entrypoints.
+Entrypoints can be activated or deactivated, depending on if the operations targeting those entrypoints
+should be sponsored or not.
 
 ![Homepage](./assets/homepage.png)
 
 ### Add a new contract
 
-To add a new contract, click on `Add contract` and fill in the required information. Start by entering the contract address to retrieve the associated entrypoints for your contract. Then, provide a name and activate the entrypoints for which you want to sponsor.
+To add a new contract, click on `Add contract` and fill in the required information. Start by entering the contract address to retrieve the associated entrypoints for your contract. Then, name the contract and activate the entrypoints which you want to sponsor.
 
 ![Add contract](./assets/add-contract.png)
 
 ### Add credits to your vault
 
-To add credits to your vault, go to the `My credits` page. Enter the amount of XTZ you want to send to your vault and confirm. After a few seconds, your vault balance and overall balance will update, and the transfer will be effective.
+The Gas Station sponsors operations to your contracts using the tez you have put in a vault. To add credits to your vault, go to the `My credits` page. Enter the amount of tez you want to send and confirm. After a few seconds, your vault balance and overall balance will be updated.
 
 ![Add credits](./assets/add-credits.png)
 
 
-### Withdraw
-
-You can also withdraw XTZ from your vault. On the `My credits` page, enter the amount of XTZ you want to withdraw and confirm. You'll need to sign the transaction with your wallet to ensure that the credits go to the correct address.
+### Withdraw credits
 
+You can also withdraw tez from your vault. On the `My credits` page, enter the amount of tez you want to withdraw and confirm. For security reasons, we require a signature which depends on the vault, the amount, and a withdraw counter which is stored in the database.
 
 ### Test
 
-Once the contract is added and credits are transferred to your vault, you can integrate the Gas Station into your dApps by following this [guide](./tutorial.md). This will allow you to test the seamless integration of the Gas Station with your dApps.
+Once the contract is added and credits are transferred to your vault, you can integrate the Gas Station into your dApps by following this [guide](./tutorial.md). This will allow you to test the seamless integration of the Gas Station with your dApps.

docs/src/welcome.md

@@ -2,9 +2,15 @@
 
 ## Introduction
 
-The Gas Station is a tool designed for developers aiming to provide sponsored transactions to their users. It can be used to facilitate user onboarding or implementing a specific economic model (e.g., the user can mint a NFT freely, but pays a fee when reselling it).
+The Gas Station is a tool allowing developers to sponsor the transactions of their users. It can be
+used to facilitate user onboarding, or to implement a specific economic model (e.g., users can
+mint a NFT freely, but pay a fee when reselling it) which does not need the user to possess tez.
 
-The Gas Station would typically be used by video game developers seeking to subsidize activities for users without any tez in their wallets. It does not require these users to do any transaction or reveal their account, as the Gas Station account independently processes those transactions. However, it's important to note that this workflow may necessitate the use of specific smart contract patterns, such as permit (TZIP 17).
-
-Currently, the API URL for Ghostnet is: [https://ghostnet.gas-station-api.marigold.dev](https://ghostnet.gas-station-api.marigold.dev). The Gas Station is not yet available on the Mainnet.
+The Gas Station would typically be used by video game developers to subsidize activities for
+users. It does not require these users to do any transaction or reveal their account, as the Gas
+Station account independently processes those transactions. However, it's important to note that
+this workflow may necessitate the use of specific smart contract patterns, such as permit (TZIP 17).
 
+Currently, the API URL for Ghostnet is:
+[https://ghostnet.gas-station-api.marigold.dev](https://ghostnet.gas-station-api.marigold.dev). The
+Gas Station is not yet available on the Mainnet.