Explore foundry-tags for automating releases

[PaulRBerg]

See @sambacha's project foundry-tags:

https://github.com/sambacha/foundry-tags

[sambacha]

Thanks paul, let me just lay it out here.

Versioning, Natspec, and Documentation all in one: DappSpec

Dappspec deals with the lifecycle of a contract deployment, namely release management and distribution for consumption. The motivating factor really is for being able to reliably assert which version of a protocol we are dealing with. Protocols are rarely released simultaneously on all chains, ergo there are differences in their deployments and interfaces. This causes issues when trying to automate/integrate cross-chain.

Dappspec aims to help enable trustless exchange of protocol interfaces and relevant information for intergrations.

Versioning (foundry-tags)

Much of this builds on Rich Hickey's talk, 'Spec-Ulation'

There are two orthogonal problems when importing an external dependency (generally):

Availability: Will A be available at the host site?
Compatibility: Will the version of A available at the host is compatible with P?

Versioning in this regard is referred to as Accretive Versioning¹

Accretive versioning is based on matching type signatures against a generated ABI V2.

Imagine a package manager that ran the test suite of the version you're currently using against the code of the version you'd like to upgrade to, and told you exactly what wasn't going to work. This is a lofty goal, and for the purposes of this discussion worthwhile to mention but beyond the scope of this spec (and intro).

Basically, take the compiler's ABI-generated artifact, and generate a solidity interface from that ABI, that is your 'version'. Mark functions depreciated minor increments or patch. Those specifics I have not narrowed down yet, but I think the idea of automated versioning via diffing generated interfaces warrants further investigation as it's simple, robust (at least for our purposes, YMMV when traveling into other ecosystems), and best of all, automated. The issues with Semver et al are all due to the human inference into the process of creating a versioned release, which is why you see such applications such as changesets / semantic versioning CI pipelines that try to automate this away from developers' interjections.

Additionally, with well-versioned artifacts, things like scoping become easier to do. Note that I mention this here only to provide additional context as to how an implementation may look like for persisting that sort of versioning information (hint: it is not going to be in your TOML file).

Forge Tags

Originally the issue I was wanting to resolve was not using git submodules. There is a GitHub action at the repo that handles git tagging with these semantics (not this is not per see Accretive Versioning!)

Forge Tagging Releases GitHub Action

By default, if you do not pass a tags input this action will use an algorithm based on the state of your git repo to determine the Foundry/DPack tag(s).
Below is a table detailing how the GitHub trigger (branch or tag) determines the Foundry tag(s).

Trigger	Commit SHA	addLatest	addTimestamp	Foundry Tag(s)
/refs/tags/v1.0	N/A	false	N/A	v1.0
/refs/tags/v1.0	N/A	true	N/A	v1.0,latest
/refs/heads/dev	1234567	false	true	dev-1234567-2021-09-01.195027
/refs/heads/dev	1234567	true	false	dev-1234567,latest
/refs/heads/master	1234567	false	true	master-1234567-2021-09-01.195027
/refs/heads/master	1234567	true	false	master-1234567,latest
/refs/heads/SOME-feature	1234567	false	true	some-feature-1234567-2021-09-01.195027
/refs/heads/SOME-feature	1234567	true	false	some-feature-1234567,latest

The Accretive versioning spec is not formalized yet, so would like to hear any feedback at all.

Dappspec: @custom/natspec:

Dappspec takes the @custom:... natspec tag and provides a list of admonitions for generating documentation for Solidity contracts.

The Specifics Admonitions include identifiers for code blocks that reference gas optimizations, assembly blocks and emit events.

The @Custom: security tag is used by OpenZeppelin for identifying the point of contact. Similar to security.txt, see an example here

The General Admonitions are meant to render the docstring content as a code block that you would find in generators like mkdocs. see squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types

The style of how to do @custom tags is not decided yet, in fact I just yesterday added the container OCI schema as a potential way of doing it

/**
 * @custom:org.label-schema.security='ops@manifoldfinance.com'
 * @custom:org.label-schema.support='github.com/manifoldfinance/support'
 * @custom:org.label-schema.vcs-url='github.com/manifoldfinance'
 * @custom:org.label-schema.vendor='CommodityStream, Inc'
 * @custom:org.label-schema.schema-version="1.0"
 */

Documentation:

Autogenerated and opinionated: this is from the 'literate programming' movement, originally sourced from 'groc', see more here https://github.com/nevir/groc/blob/master/README.md

Basically, This all builds on each other: Versioned well documented and oriented towards lowering friction both on the developer side and consumer side.

Here is an example of the generated documentation for the new OpenMev Router for Sushiswap

A go binary generates the docs. It uses pygementize under the hood to provide for highlighting. No need to involve solc here :)

Here is a selected portion of the generated docs:

I think adding a 3rd slim column for margin notes would be interesting, potentially for specific natspec directives e,g, @custom:warning etc.

Thanks for posting this comment, it forced me to type all this together in a more cohesive fashion, let me know what you think, and much appreciate your work , enjoy your weekend,

---

Thanks again, and sorry for the wall of text

Footnotes

1. https://wiki.haskell.org/The_Monad.Reader/Issue2/EternalCompatibilityInTheory ↩

[PaulRBerg]

Hi @sambacha, thanks for taking the time to write such a detailed comment.

You added a reference to Eternal Compatibility Theory, suggesting that there I could find an explanation for Accretive Versioning, but searching for the word "Accretive" didn't yield any result there.

This is interesting, I'll take dappspec and the foundry-tags GitHub Action for a spin. If I may share my feedback for the latter - it would be very, very helpful to edit the README to add these things:

1. Mention that the repo is a GitHub Action.
2. Add an explicit reference to Foundry.
3. Create a bespoke Inputs section, with a table that document the input keys and value types.
4. Provide an example repo for users to see what the Action will do to it.
5. Add more details about the versioning algorithm, i.e. what is "an algorithm based on the state of your git repo". Is it semantic versioning?

[sambacha]

I am re-working this spec in the context of removing the submodule dependency management used in foundry currently. I know brock and doggie are working on a package management system as well for solidity/vyper contracts, so would like to see their thoughts.

The naive explanation of accretive versioning is doing something like generating bash completions for a command line utility and diffing between different releases to see if there is any substantive changes in the exposed interface. This is most certainly a naive explanation as there are other considerations to take into account such as transitive dependencies etc that may not be necessarily related to the exposed interface but however effect packaging and distribution of the app itself.

Though I think with smart contracts that are deployed, we can know if its a type of prefab / gem (i.e. from factory), does the same thing in principle ya?