Add a docs/ directory containing a mkdocs website

Author: fbeutin-ledger

.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/img/Ledger-logo-696.webp

@@ -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/index.md

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

docs/requirements.txt

@@ -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/diagram.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/globals.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_finalize.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_init_contract.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"
+```