Merge pull request #22 from LedgerHQ/fbe/doc_test

Add a docs/ directory containing a mkdocs website

.github/workflows/publish_doc_website.yml

@@ -0,0 +1,44 @@
+---
+name: Publish docs via GitHub Pages
+on:
+ workflow_dispatch:
+ push:
+ branches:
+ - develop
+
+permissions:
+ contents: write
+
+jobs:
+ build:
+ name: Deploy docs
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Checkout plugin-boilerplate
+ uses: actions/checkout@v4
+ with:
+ path: ./app-plugin-boilerplate
+ repository: LedgerHQ/app-plugin-boilerplate
+ ref: develop
+
+ - name: Configure Git Credentials
+ run: |
+ git config --global user.name "github-actions[bot]"
+ git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+ - name: Install python
+ uses: actions/setup-python@v5
+ with:
+ python-version: 3.x
+
+ - name: Install requirements
+ run: pip install -r docs/requirements.txt
+
+ - name: Deploy docs
+ run: |
+ mkdocs gh-deploy --force
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,2 @@
+# Ignore mkdocs build
+site/

README.md

@@ -1,4 +1,5 @@
 # ethereum-plugin-sdk
 
-This repository is meant to be linked as submodule and used in external plugins working with [app-ethereum](https://github.com/LedgerHQ/app-ethereum).
-It is composed of a few headers containing definitions about app-ethereum's internal transaction parsing state and some structures to communicate via shared memory.
+This repository is meant to be used as a submodule for ethereum plugins working with [app-ethereum](https://github.com/LedgerHQ/app-ethereum).
+
+Please find the full documentation here [ethereum-plugin-sdk](https://ethereum-plugin-sdk.ledger.com).

docs/index.md

@@ -0,0 +1,51 @@
+# Ethereum plugin documentation
+
+This documentation will help you design your own ethereum plugin.
+
+## What is a plugin?
+
+A plugin is a lightweight application that only performs smart contract parsing and leverages the Ethereum application for the rest.
+
+Your plugin will allow your users to clear-sign your smart contracts when using a Ledger device.
+
+Plugins are designed to work hand-in-hand with the Ethereum application:
+
+- The plugin handle the smart contract parsing
+- The Ethereum application handles everything else (APDU reception, signature, screen management, bluetooth, etc)
+
+Upon your smart contract reception, the Ethereum application will call your plugin to query the elements to display and your plugin will be responsible for:
+
+- Extracting the relevant information from the smart contract.
+- Replying the string to be displayed back to the Ethereum App.
+
+## Coding my own plugin
+
+### Use the Ethereum Plugin SDK
+
+Use the Ledger developed [Ethereum Plugin SDK](https://github.com/LedgerHQ/ethereum-plugin-sdk).<br/>
+The SDK will do all the busy work of your plugin and leave you with only a few handlers to code.<br/>
+The SDK is designed to be used as a git submodule.
+
+!!! note
+ Always keep your SDK up to date with its **develop** branch.<br/>
+ We are providing a CI workflow to help you check that the latest version is being used.
+
+### Fork the Plugin Boilerplate
+
+While starting a new plugin application from a blank repository + the SDK is technically possible, it is not *at all* recommended and support would not be provided.<br/>
+Instead, fork our official template application [Plugin Boilerplate](https://github.com/LedgerHQ/app-plugin-boilerplate) and start from there.
+
+You will start with a correct build structure, examples of handlers, our test framework working, and the CI workflows already setup.
+
+## Plugin file structure
+
+- `.github/workflows`: the [CI workflows](test_framework/ci.md) required to showcase your plugin's quality.
+- `Makefile`: The entry point of the compilation of your plugin.
+- `PLUGIN_SPECIFICATION.md`: The specification of the supported smart-contract and selectors of your plugin.
+- `ethereum-plugin-sdk/`: This repository contains the interface between the Ethereum app and your plugin, as well as a lot of utility functions.
+- `fuzzing/`: the [Fuzzer](test_framework/fuzzing.md) folder.
+- `glyphs/`: The icon displayed by the Ethereum application when using the plugin on a Touchscreen device.
+- `icons/`: The icons displayed on the device dashboard on any device.
+- `ledger_app.toml`: the [Manifest](https://github.com/LedgerHQ/ledgered/blob/master/doc/manifest.md) of your plugin, used to bridge with the Ledger developed tools.
+- `src/`: the source code of the plugin (in C).
+- `tests/`: the [tests](test_framework/ragger.md) folder.

docs/requirements.txt

@@ -0,0 +1,4 @@
+mkdocs
+pymdown-extensions
+mkdocs-material
+mkdocs-mermaid2-plugin

docs/technical_informations/diagram.md

@@ -0,0 +1,57 @@
+This diagram showcases a complete sequence of the parsing, display, and signature of a smart contract.
+
+```mermaid
+sequenceDiagram
+ participant L as Ledger Live
+ participant E as Ethereum application
+ participant SDK as Plugin SDK
+ participant P as Plugin
+ L->>E: SET_EXTERNAL_PLUGIN
+ E->>+SDK: ETH_PLUGIN_CHECK_PRESENCE
+ SDK->>-E: ack;
+ L->>+E: Transaction to sign
+ Note over E: The plugin for this smart<br/>contract exists, rely on it
+ E->>+SDK: ETH_PLUGIN_INITIALIZE
+ SDK->>+P: handle_init_contract()
+ Note over P: Your code here
+ P->>-SDK: return;
+ SDK->>-E: ;
+ Note over E: Split contract data in chunks
+ loop Send smart contract chunks
+ E->>+SDK: ETH_PLUGIN_PROVIDE_PARAMETER
+ SDK->>+P: handle_provide_parameter()
+ Note over P: Your code here
+ P->>-SDK: return;
+ SDK->>-E: ;
+ end
+ Note over E: Inform plugin that everything was sent
+ E->>+SDK: ETH_PLUGIN_FINALIZE
+ SDK->>+P: handle_finalize()
+ Note over P: Your code here
+ P->>-SDK: Number of screens needed<br/>Ask ERC20 tokens info if needed
+ SDK->>-E: ;
+ opt
+ Note over L: Knows that Ethereum<br/>will need ERC20 token info
+ L->>E: Provide ERC20 token
+ E->>+SDK: ETH_PLUGIN_PROVIDE_TOKEN
+ SDK->>+P: handle_provide_token()
+ Note over P: Your code here
+ P->>-SDK: Update screens number
+ SDK->>-E: ;
+ end
+ Note over E: Ready to start display
+ E->>+SDK: ETH_PLUGIN_QUERY_CONTRACT_ID
+ SDK->>+P: handle_query_contract_id()
+ Note over P: Your code here
+ P->>-SDK: Provide title screen
+ SDK->>-E: ;
+ loop For every screen requested
+ E->>+SDK: ETH_PLUGIN_QUERY_CONTRACT_UI
+ SDK->>+P: handle_query_contract_ui()
+ Note over P: Your code here
+ P->>-SDK: Provide screen
+ SDK->>-E: ;
+ end
+ Note over E: User validates or rejects
+ E->>-L: Transaction signed / rejected
+```

docs/technical_informations/globals.md

@@ -0,0 +1,15 @@
+!!! warning
+ Global variables should **never** be used in your plugin. Only the semi-persistent context provided by the Ethereum application should be used.
+
+Each call by the Ethereum application starts the plugin anew with a fresh main call: everything not saved in the context is lost.
+
+In order to retain knowledge from a handler call to another, the plugin can use a memory section allocated by the Ethereum application.
+
+The context can be accessed through the `uint8_t *pluginContext` field of the parameter. All handlers will pass it to your plugin and it's common to your plugin's lifetime from the init call to the display.
+
+The ethereum application will never modify the content of the structure.
+
+This is the size available for the context of your plugin:
+```c
+--8<-- "src/eth_plugin_interface.h:plugin_context"
+```

docs/technical_informations/handlers/handle_finalize.md

@@ -0,0 +1,11 @@
+# handle_finalize()
+
+## Handle explanation
+
+--8<-- "src/eth_plugin_interface.h:handle_finalize_explanation"
+
+## Fields descriptions
+
+```c
+--8<-- "src/eth_plugin_interface.h:handle_finalize_parameters"
+```

docs/technical_informations/handlers/handle_init_contract.md

@@ -0,0 +1,11 @@
+# handle_init_contract()
+
+## Handle explanation
+
+--8<-- "src/eth_plugin_interface.h:handle_init_contract_explanation"
+
+## Fields descriptions
+
+```c
+--8<-- "src/eth_plugin_interface.h:handle_init_contract_parameters"
+```

docs/technical_informations/handlers/handle_provide_parameter.md

@@ -0,0 +1,11 @@
+# handle_provide_parameter()
+
+## Handle explanation
+
+--8<-- "src/eth_plugin_interface.h:handle_provide_parameter_explanation"
+
+## Fields descriptions
+
+```c
+--8<-- "src/eth_plugin_interface.h:handle_provide_parameter_parameters"
+```

docs/technical_informations/handlers/handle_provide_token.md

@@ -0,0 +1,19 @@
+# handle_provide_token()
+
+## Handle explanation
+
+--8<-- "src/eth_plugin_interface.h:handle_provide_token_explanation"
+
+## Fields descriptions
+
+```c
+--8<-- "src/eth_plugin_interface.h:handle_provide_token_parameters"
+```
+
+## Provided token structure
+
+This is the structure given by the Ethereum application to the plugin.
+
+```c
+--8<-- "src/asset_info.h:asset_info"
+```

docs/technical_informations/handlers/handle_query_contract_id.md

@@ -0,0 +1,11 @@
+# handle_query_contract_id()
+
+## Handle explanation
+
+--8<-- "src/eth_plugin_interface.h:handle_query_contract_id_explanation"
+
+## Fields descriptions
+
+```c
+--8<-- "src/eth_plugin_interface.h:handle_query_contract_id_parameters"
+```

docs/technical_informations/handlers/handle_query_contract_ui.md

@@ -0,0 +1,19 @@
+# handle_query_contract_ui()
+
+## Handle explanation
+
+--8<-- "src/eth_plugin_interface.h:handle_query_contract_ui_explanation"
+
+## Fields descriptions
+
+```c
+--8<-- "src/eth_plugin_interface.h:handle_query_contract_ui_parameters"
+```
+
+## Provided token structure
+
+This is the structure given by the Ethereum application to the plugin.
+
+```c
+--8<-- "src/asset_info.h:asset_info"
+```

docs/technical_informations/handlers/index.md

@@ -0,0 +1,10 @@
+# Handlers
+
+Handlers are callbacks that the Ethereum application calls through the Ethereum plugin SDK to parse and display a smart contract. 
+
+This is the list of all handlers that each plugin must define:
+```c
+--8<-- "src/eth_plugin_interface.h:handlers_functions"
+```
+
+Please look at the [sequence diagram](../diagram.md) to better understand at which step each handler is called.

docs/technical_informations/index.md

@@ -0,0 +1,3 @@
+Please find in this section technical information helpful for coding your plugin.
+
+Only technical information specific to plugin development are written here.

docs/technical_informations/tx_content.md

@@ -0,0 +1,5 @@
+--8<-- "src/tx_content.h:tx_content_explanation"
+
+```c
+--8<-- "src/tx_content.h:tx_content_structures"
+```

docs/technical_informations/utils/common_utils.md

@@ -0,0 +1,3 @@
+```c
+--8<-- "src/common_utils.h:common_utils"
+```

docs/technical_informations/utils/index.md

@@ -0,0 +1,3 @@
+Utility functions are provided by the Ethereum Plugin SDK to help you code your plugin.
+
+They are complementary to the utility functions of the main SDK.

docs/technical_informations/utils/plugin_utils.md

@@ -0,0 +1,3 @@
+```c
+--8<-- "src/plugin_utils.h:plugin_utils"
+```

docs/test_framework/ci.md

@@ -0,0 +1 @@
+--8<-- "app-plugin-boilerplate/.github/workflows/README.md"

docs/test_framework/fuzzing.md

@@ -0,0 +1 @@
+--8<-- "app-plugin-boilerplate/fuzzing/README.md"

docs/test_framework/index.md

@@ -0,0 +1,9 @@
+The folowing test elements are mandatory for your plugin:
+
+- functionnal tests
+- fuzzing
+- CI
+
+A documentation page is provided here for each required element.
+
+This pages are extracted from the plugin-boilerplate sources.

docs/test_framework/ragger.md

@@ -0,0 +1 @@
+--8<-- "app-plugin-boilerplate/tests/README.md"

docs/walkthrough/index.md

@@ -0,0 +1,52 @@
+
+This page will walk you through developing your plugin, from the Boilerplate fork to the functional tests.<br/>
+Sections of the template code you can edit are commented with a `EDIT THIS` marker.
+
+## Change the plugin metadata
+
+In the `Makefile` you will need to change the following elements:
+
+- `APPNAME` to suit your plugin name (e.g., Paraswap, 1inch, Lido)
+- `APPVERSION` for your plugin version
+
+## Change the plugin icons
+
+In the `icons/` and `glyphs/` directory, rename the images to include your `APPNAME` instead of the `pluginboilerplate` name.<br/>
+Change the picture provided to use one suitable for your plugin.<br/>
+Don't forget to refer to the [documentation](https://developers.ledger.com/docs/device-app/deliver/deliverables/icons#device-icon).<br/>
+Incompatible icons will be detected by the CI.
+
+## Change the selectors
+
+Let’s go to the first `EDIT THIS` comment in `app-plugin-boilerplate/src/plugin.h`. In this file you can list all the selectors for each contract. The template uses uses two selectors but you are not limited. <br/>
+Enter your selectors here, in the format X(NAME, value).
+
+### Example: Let's support `SwapExactEthForToken` from Uniswap V2
+
+You can find it using Etherscan, and you can also compose it using the ABI (Application Binary Interface).
+
+By looking at [recent transactions on Uniswap](https://etherscan.io/txs?a=0x7a250d5630b4cf539739df2c5dacb4c659f2488d), we find a transaction with the `SwapExactEthForToken` method. Here is [an example](https://etherscan.io/tx/0x216bfa6fb8488901d168810cda1b716d1abcb002a87c3224180deaff00c950fc).
+
+Let's scroll down and click on "Click to see more", to read:
+
+![Screenshot](img/uniswap.webp)
+
+The header line shows `Method ID` to be `0x7ff36ab5`.
+This is going to be the 4 bytes of `SWAP_EXACT_ETH_FOR_TOKENS_SELECTOR`:
+
+```c
+#define SELECTORS_LIST(X)  \
+ X(SWAP_EXACT_ETH_FOR_TOKENS_SELECTOR, 0x7ff36ab5)
+```
+
+## Update the `PLUGIN_SPECIFICATION.md` file
+
+Please update the `PLUGIN_SPECIFICATION.md` file at the root of the project to include your smart contract and selectors.
+
+## Adapt the handlers
+
+Now we have to change each handler to parse and display your smart contract.
+
+We advise you to stick to the file structure done in plugin-boilerplate and keep each handler in a dedicated file.
+
+Please look at the [sequence diagram](../technical_informations/diagram.md) to better understand at which step each handler is called.