# ink! Analyzer: Retroactive funding for ink! v5 support

Hello, I'm [David Semakula (@davidsemakula)][me] - the creator of [ink! analyzer][ink-analyzer].

[me]: https://github.com/davidsemakula
[ink-analyzer]: https://github.com/ink-analyzer

## What's ink! analyzer?
[ink! analyzer][ink-analyzer] is a collection of modular and reusable libraries and tools for semantic analysis of [ink!] smart contracts.

In short, ink! analyzer is to ink!, what [rust-analyzer] is to [Rust].

[ink!]: https://use.ink
[rust-analyzer]: https://github.com/rust-lang/rust-analyzer
[Rust]: https://www.rust-lang.org/

More technically, rust-analyzer is a Rust compiler frontend/semantic analyzer for [IDEs][IDE] that's built on 
a lossless and resilient parser (this part is very important for IDE/editor tooling because the program is essentially 
perpetually incorrect as you type in an IDE/editor). So rust-analyzer "understands" core Rust language concepts 
(e.g. that a trait implementation like `impl MyTrait for MyStruct {}` must define all the required associated items of the trait), 
and provides [intelligent editing features][intellisense] to help you with those kinds of core Rust language features.

However, when it comes to [Rust syntax extensions/DSLs like ink!'s attribute macros][ink-macros], 
when you annotate a `mod` item with `#[ink::contract]`, all rust-analyzer "knows" is that this is a custom attribute, 
it doesn't "know" that an ink! contract `mod` must have exactly one `struct` item annotated with `#[ink(storage)]` 
or any of the other semantic rules for ink! contracts, so this is where ink! analyzer comes in 🙂.

[IDE]: https://en.wikipedia.org/wiki/Integrated_development_environment
[intellisense]: https://code.visualstudio.com/docs/editor/intellisense
[ink-macros]: https://use.ink/getting-started/creating-an-ink-project/

For a deeper dive on the problems ink! analyzer solves and technical details about its architecture, 
check out [this detailed introductory blog post][ink-analyzer-intro].
You can also check out [this awesome X/Twitter thread by the ink! lang team][twitter-thread] for a quick walkthrough of ink! analyzer features.

[ink-analyzer-intro]: https://analyze.ink/blog/introducing-ink-analyzer
[twitter-thread]: https://twitter.com/ink_lang/status/1762795949259448776

## Adoption

ink! analyzer's most user/developer facing component is currently a [Visual Studio Code extension][vs-code-extension], 
which has over *~350 unique installs* (first released in Aug/2023).

However, ink! analyzer is built with an IDE/editor agnostic architecture to maximize re-usability of it's core components i.e.
- [A modular domain-specific semantic analysis library for ink!][semantic-analyzer] built on a resilient and lossless parser.
- A [Language Server Protocol (LSP)][LSP] [implementation][lsp-server] built on top of the aforementioned semantic analysis library.

![ink! Analyzer - LSP based Architecture Diagram](https://davidsemakula.com/static/images/ink-analyzer/w3f/architecture.png "ink! Analyzer - LSP based Architecture Diagram")
*Figure 1: ink! Analyzer - LSP based Architecture Diagram*

These two components (i.e. the [semantic analyzer][semantic-analyzer] and [language server][lsp-server]) can be reused 
to add ink! language support to multiple IDEs, code editors and other development tools.
In particular, a large number of IDEs and code editors support LSP servers, these include 
[Visual Studio Code, Visual Studio, Vim / Neovim, Emacs, Atom, Sublime Text, Acme, Lapce, Eclipse and many more][lsp-tools].

[semantic-analyzer]: https://github.com/ink-analyzer/ink-analyzer/tree/master/crates/analyzer
[lsp-server]: https://github.com/ink-analyzer/ink-analyzer/tree/master/crates/lsp-server
[vs-code-extension]: https://marketplace.visualstudio.com/items?itemName=ink-analyzer.ink-analyzer
[LSP]: https://microsoft.github.io/language-server-protocol/
[lsp-tools]: https://microsoft.github.io/language-server-protocol/implementors/tools/

Therefore, ink! analyzer makes it relatively easy for:

- Users to enable ink! language support for their IDE, code editor or other development tool if it has either
  a native/built-in or third-party LSP client that can be configured to launch an LSP server using an executable command
  (i.e. the path to an [installed ink! Language Server binary][lsp-server-install])
  and can use stdio (standard in/standard out) as the message transport.
- Developers to either build extensions/plugins/integrations that add ink! language support to any tool with robust
  LSP client libraries/APIs/modules, or add first-class ink! language support to an existing LSP client
  (e.g. an open-source extension/plugin/integration).

[lsp-server-install]: https://github.com/ink-analyzer/ink-analyzer/tree/master/crates/lsp-server#installation

The latter option typically provides a better user experience as the user doesn't have to manually install (and update)
the ink! Language Server as it can be bundled (or installed/updated) by the extension/plugin/integration. 
The [Visual Studio Code extension][vs-code-extension] serves as a showcase and 
[reference implementation][vs-code-extension-src] for this use case/approach.

However, ink! analyzer also [distributes compiled ink! Language Server (`ink-lsp-server`) binaries for most of the major platforms/architectures][ink-lsp-server-releases] 
for non-VS Code users and developers. 

[vs-code-extension-src]: https://github.com/ink-analyzer/ink-vscode
[ink-lsp-server-releases]: https://github.com/ink-analyzer/ink-analyzer/releases

**NOTE:** While the first version of the [ink! analyzer VS Code extension][vs-code-extension] was released in Aug/2023, 
work on the core components (i.e. [semantic analyzer][semantic-analyzer] and [language server][lsp-server]) started well before in Mar/2023.

## Proposal Ask

This treasury proposal requests *retroactive funding* for adding [ink! v5][ink-v5] support to ink! analyzer.

Requested Amount: $26,500 / 2,812.27 DOT[^1]

[ink-v5]: https://github.com/paritytech/ink/releases/tag/v5.0.0

| Breakdown/Tasks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Hours       |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| Add architectural foundations for supporting both v4 and v5 language versions across [IR, semantic analyzer and language server][ink-analyzer-architecture]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | ~24         |
| Update IR (Intermediate Representation) and attribute parser to support all v5 syntax and entities (including deeply nested meta-items and @ selector values) while preserving legacy support for v4 (also includes unit tests)                                                                                                                                                                                                                                                                                                                                                                                                                                        | ~80         |
| Add diagnostics and quickfixes for v5 entities and related attribute macros and arguments (while preserving legacy support for v4) <br/> <ul><li>Add v5 wildcard and wildcard complement selector validation</li><li>Add v5 chain extension and associated extension function validation</li><li>Add support for Events 2.0 (i.e. new `ink::event` macro in addition to the existing `ink(event)` attribute arguments)</li><li>Add v5 nested attribute arguments validation and support for e2e backend options</li><li>Add support for `ink::scale_derive` attribute macro</li><li>Unit tests</li></ul>                                                               | ~136        |
| Add v5 support for completions, code/intent actions, hover content, inlay hints and signature help (while preserving legacy support for v4) <br/> <ul><li>Add support for v5 completions</li><li>Add support for v5 code actions</li><li>Add hover content for v5 attribute macros and arguments (while preserving v4 content for legacy support)</li><li>Add support for v5 inlay hints</li><li>Add support for v5 signature help</li><li>Unit tests</li></ul>                                                                                                                                                                                                        | ~96         |
| Add v5 codegen (while preserving legacy support for v4)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | ~8          |
| General maintenance and performance improvements <br/> <ul><li>Suggest unique ids for selectors and extensions in completions, quickfixes and code/intent actions</li><li>Suggest unique names for ink! constructor, message, extension, test and e2e test `fn`s, ink! event `struct` and ink! topic field names in quickfixes and code/intent actions</li><li>Suggest `ink::env::DefaultEnvironment` or an ADT that `impl ink::env::Environment` for ink! env/environment args in completions, quickfixes and code/intent actions</li><li>Performance improvements (e.g sharing analysis snapshots to reduce computation and allocation)</li><li>Unit tests</li></ul> | ~48         |
| Integration tests (across semantic analyzer, language server and VS Code extension)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | ~24         |
| Documentation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | ~8          |
| **Total Hours**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | **~424**    |
| **Hourly Rate**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | **$62.5**   |
| **Total Amount**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | **$26,500** |

**NOTE:** All ink! analyzer components are [fully open-source][ink-analyzer] and distributed under [OSI approved licenses][OSI-licenses].

[ink-analyzer-architecture]: https://github.com/ink-analyzer/ink-analyzer/blob/master/README.md#architecture
[OSI-licenses]: https://opensource.org/licenses

## Previous Funding

All previous work for ink! analyzer was funded by two generous [Web3 Foundation technical grants][w3f-grants].

- https://github.com/w3f/Grants-Program/blob/master/applications/ink-analyzer.md ($30,000)
- https://github.com/w3f/Grants-Program/blob/master/applications/ink-analyzer-phase-2.md ($59,600)

However, with the project now relatively mature and having some meaningful adoption, 
I'm looking to move to a retroactive treasury funding model for future updates.

**NOTE:** [ink! v5][ink-v5] has only recently been released (13/Mar/2024), 
and so was outside the scope of the above [Web3 Foundation][w3f-grants] technical grants. 
However, work on ink! v5 support in ink! analyzer started well before the official ink! v5 release.

[w3f-grants]: https://grants.web3.foundation/

## Why not Wasm Smart Contracts Bounty / ink!ubator ?

Historically, as noted above, all previous work for ink! analyzer was funded by [Web3 Foundation technical grants][w3f-grants].
This is partly because [development of ink! analyzer kicked off in Mar/2023][ink-analyzer-pr], 
while the [ink!ubator: Ecosystem Grants][inkubator-grants] program 
[only started receiving grant applications around ~May/2023][inkubator-pr]
(note that discussions for the [Wasm Smart Contracts Bounty][wasm-bounty] started well before this though).

In the present, with [ink!ubator being an incubation program following a cohort schedule][inkubator], 
and ink! analyzer now being a relatively mature project with some meaningful adoption, the need to support 
new [ink! features and syntax][ink-v5] as close to release as possible (hence the choice of retroactive funding), 
means the ink!ubator cohort schedule is not a good fit for this stage of the project.

[ink-analyzer-pr]: https://github.com/w3f/Grants-Program/pull/1615
[inkubator]: https://use.ink/ubator
[inkubator-grants]: https://github.com/use-inkubator/Ecosystem-Grants
[inkubator-pr]: https://github.com/use-inkubator/Ecosystem-Grants/pull/7
[wasm-bounty]: https://polkadot.polkassembly.io/bounty/19

## More about the author.

I'm an independent Software Engineer & Systems Architect with over 10+ years of experience.

I also [*independently* contribute][ra-contributions] to [rust-analyzer] (a Rust compiler front-end for IDEs).

I've also made some [*independent* contributions][ink-contributions] to [ink!][ink-repo].

You can check out my [GitHub profile][me] and/or my [personal website][website] for more details.

[website]: https://davidsemakula.com/
[ra-contributions]: https://github.com/rust-lang/rust-analyzer/pulls?q=is%3Apr+author%3Adavidsemakula
[ink-contributions]: https://github.com/paritytech/ink/pulls?q=is%3Apr+author%3Adavidsemakula
[ink-repo]: https://github.com/paritytech/ink

[^1]: DOT/USD rate uses EMA30 rate from [Subscan](https://polkadot.subscan.io/tools/charts?type=price) retrieved on 27/Mar/2024.

- **Problem Statement & Audience:** Requesting retroactive funding for adding ink! v5 support to ink! analyzer.
- **Significance:** Enhancing ink! analyzer to support ink! v5 features for improved semantic analysis.
- **Proposed Solution:** Detailed breakdown of tasks including updating IR, adding diagnostics, completions, code actions, codegen, maintenance, and documentation.
- **Expected Outcomes:** Enabling ink! language support for various IDEs and tools, enhancing user experience, and supporting ink! v5 features.

#747 ink! Analyzer: Retroactive funding for ink! v5 support