{"id":15683589,"url":"https://github.com/sambacha/dappspec","last_synced_at":"2026-03-11T13:38:55.721Z","repository":{"id":40779485,"uuid":"503777672","full_name":"sambacha/dappspec","owner":"sambacha","description":"dappspec is an extended natspec and generator in one ","archived":false,"fork":false,"pushed_at":"2025-04-28T05:39:15.000Z","size":325,"stargazers_count":10,"open_issues_count":12,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-11T01:57:10.135Z","etag":null,"topics":["admonitions","dappspec","devdocs","documentation","ethereum","natspec","solidity","uerdoc","vale"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sambacha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-15T13:29:26.000Z","updated_at":"2025-04-28T05:39:20.000Z","dependencies_parsed_at":"2025-05-07T13:56:06.494Z","dependency_job_id":null,"html_url":"https://github.com/sambacha/dappspec","commit_stats":{"total_commits":81,"total_committers":1,"mean_commits":81.0,"dds":0.0,"last_synced_commit":"34bc825e8e68bb88c46caaff4f803331c9d3c2c1"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/sambacha/dappspec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sambacha%2Fdappspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sambacha%2Fdappspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sambacha%2Fdappspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sambacha%2Fdappspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sambacha","download_url":"https://codeload.github.com/sambacha/dappspec/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sambacha%2Fdappspec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30382673,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T12:49:11.341Z","status":"ssl_error","status_checked_at":"2026-03-11T12:46:41.342Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admonitions","dappspec","devdocs","documentation","ethereum","natspec","solidity","uerdoc","vale"],"created_at":"2024-10-03T17:07:28.201Z","updated_at":"2026-03-11T13:38:55.704Z","avatar_url":"https://github.com/sambacha.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\ntitle: DAppSpec\nversion: v2022.06.26, v2022.07.13, v2022.07.19, v2022.08.23, 2022.12.17\nauthors: \u003cTBD\u003e\nlicense: CC-SA-2.5\n---\n\n# dappspec\n\n## tl:dr\n\n\u003e\n\u003e - use clear names to answer 'what'\n\u003e - use clear statements to answer 'how'\n\u003e - use comments to answer 'why'\n\u003e\n\u003e - Nikolai Mushegian\n\n## Overview\n\n`dappspec` provides a CSS library for generating documentation from solidity natspec, you can find the preliminary library over at [https://github.com/sambacha/dappspec-css](https://github.com/sambacha/dappspec-css)\n\n\u003e This repo is a working repo for ideation and documentation.\n\n\u003e NEW: OCI for Contracts\n\u003e OLD: NatSpec for frontend usage + Admonitions as @custom:tags\n\n## Style Guide: Flight Rules\n\n\u003e informative style guide\n\nWhat are \"flight rules\"?\n\nA guide for astronauts about what to do when things go wrong.\n\n\u003e Flight Rules are the hard-earned body of knowledge recorded in manuals that list, step-by-step, what to do if X occurs, and why. Essentially, they are extremely detailed, scenario-specific standard operating procedures. [...]\n\n\u003e NASA has been capturing our missteps, disasters and solutions since the early 1960s, when Mercury-era ground teams first started gathering \"lessons learned\" into a compendium that now lists thousands of problematic situations, from engine failure to busted hatch handles to computer glitches, and their solutions.\n\n\u003e — Chris Hadfield, An Astronaut's Guide to Life on Earth.\n\n\n## Example of @custom:natspec\n\n```jsdoc\n/**\n * @custom:org.label-schema.security='ops@manifoldfinance.com'\n * @custom:org.label-schema.support='github.com/manifoldfinance/support'\n * @custom:org.label-schema.vcs-url='github.com/manifoldfinance'\n * @custom:org.label-schema.vendor='CommodityStream, Inc'\n * @custom:org.label-schema.schema-version=\"1.0\"\n */\n```\n## Motivation\n\nDappspec takes the `@custom:...` natspec tag and provides a list of admonitions for generating documentation for Solidity contracts.\n\n- The Specifics Admonitions include identifiers for codeblocks that reference `gas` optimizations, `assembly` blocks, and `emit` events.\n\n- The `@custom:security` tag as used by OpenZeppelin for identifiying the point of contact. Similar to `security.txt`, [see an example here](https://www.manifoldfinance.com/.well-known/security.txt)\n\n- 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](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types)\n\n\n\n\n### `natspec-documentation-default`.\n\n The following `SHOULD` trigger an error:\n \n * A `public` or `external` function which does not have a NatSpec comment\n   \n   * NatSpec comment does not have a `@notice` set\n   * NatSpec comment does not have a `@param` for every parameter\n   * NatSpec comment does not have a `@return` for every return\n * A `public` storage variable which does not have a NatSpec comment\n   \n   * NatSpec comment does not have a `@notice` set\n   * NatSpec comment does not have a `@param` for every parameter\n   * NatSpec comment does not have a `@return` for every return\n * An `Error` type which does not have a NatSpec comment\n   \n   * NatSpec commend does not have a `@notice` set\n \n The Solidity project recommends the above. It is extremely useful. And few people do it. So it will be very helpful to add rules for it.\n \n  It is recommended that Solidity contracts are fully annotated using NatSpec for all public interfaces (everything in the ABI).\n  [docs.soliditylang.org/en/v0.8.6/style-guide.html?highlight=style%20guide#natspec](https://docs.soliditylang.org/en/v0.8.6/style-guide.html?highlight=style%20guide#natspec)\n \n### `natspec-documentation-admonition`.\n Admonitions `(`Warning`/`Tip`/`Important`)`\nUsing specific syntax inside block quote to indicate the following content is Note.\n\n\u003cpre\u003e\n\u003e [!NOTE]\n\u003e \u003cnote content\u003e\n\u003e [!WARNING]\n\u003e \u003cwarning content\u003e\n\u003c/pre\u003e\n\nThe above content will be transformed to the following html:\n\n```html\n\u003cdiv class=\"NOTE\"\u003e\n  \u003ch5\u003eNOTE\u003c/h5\u003e\n  \u003cp\u003enote content\u003c/p\u003e\n\u003c/div\u003e\n\u003cdiv class=\"WARNING\"\u003e\n  \u003ch5\u003eWARNING\u003c/h5\u003e\n  \u003cp\u003eWARNING content\u003c/p\u003e\n\u003c/div\u003e\n```\n\nHere are all the supported note types with the styling of the default theme applied:\n\n```\n[!NOTE] This is a note which needs your attention, but it's not super important.\n\n[!TIP] This is a note which needs your attention, but it's not super important.\n\n[!WARNING] This is a warning containing some important message.\n\n[!IMPORTANT] This is a warning containing some important message.\n\n[!CAUTION] This is a warning containing some important message.\n```\n\n\u003cbr\u003e\n \n### `natspec-documentation-internal`.\n \n * An `internal` function which does not have a NatSpec comment\n   \n   * NatSpec comment does not have a `@param` for every parameter\n   * NatSpec comment does not have a `@return` for every return\n \n Note that `@notice` is not required in this circumstance because that tag applies to \"end users\" whereas an `internal` function is useful only to contract developers.\n \n Note that `private` functions are not included in this rule. This is because documentation for implementation details is always less important that documentation for an objects' surface area. If you like, this could be another rule `natspec-documentation-private` and should be default OFF.\n \n\u003e**Note**      \n\u003e Credit to fulldecent, [see this comment](https://github.com/protofire/solhint/issues/298)\n \n## Admonitions\n\n- French\n\n\u003cpre\u003e\n:::note{label=\"Il ne faut rien laisser au hasard.\"}\nBattre le fer pendant qu’il est chaud.\n:::\n\u003c/pre\u003e\n\n\u003e **Warning** \u003cbr /\u003e\n\u003e GitHub Warning\n\n\u003e **Note** \u003cbr /\u003e\n\u003e GitHub Note\n\n### General\n- check\n- important\n- warning, caution, attention\n\n### Specifics\n-    gas\n-    assembly\n-    emit \n-    security\n\n\n### Colouring Tokens\n\n\u003e md-code-hl\n\n\u003cpre\u003e\nnumber-color\nspecial-color\nfunction-color\nconstant-color\nkeyword-color\nstring-color\nname-color\noperator-color\npunctuation-color\ncomment-color\ngeneric-color\nvariable-color\n\u003c/pre\u003e\n\n## Examples\n\n## protected variable id for detector\n\n```solidity\ncontract Internal {\n    /// @custom:security write-protection=\"onlyOwner()\"\n    address owner;\n```\n\n\n### `@custom:emit` \n\n```solidity\n// try / catch flashloan arb. In case arb reverts, user swap will still succeed.\ntry bento.flashLoan(IFlashBorrower(address(this)), address(this), output, amountIn, params) {\n    /// @custom:emit MEV success\n    emit MEV(msg.sender, output, optimalReturns - ((amountIn * 5) / 10000));\n} catch {\n    /// @custom:emit MEV fail flashloan\n    emit LoanError(output, amountIn);\n```\n\n### `@custom:gas` \n\n```solidity\n    /// @custom:gas Uint256 zero check gas saver\n    /// @notice Uint256 zero check gas saver\n    /// @param value Number to check\n    function _isZero(uint256 value) internal pure returns (bool boolValue) {\n        assembly {\n            boolValue := iszero(value)\n        }\n    }\n\n    /// @custom:gas Uint256 not zero check gas saver\n    /// @notice Uint256 not zero check gas saver\n    /// @param value Number to check\n    function _isNonZero(uint256 value) internal pure returns (bool boolValue) {\n        assembly {\n            boolValue := iszero(iszero(value))\n        }\n    }\n```\n\n#### OpenZeppelin Style\n\n```solidity\n    \n    abstract contract ERC2771Context is Context {\n    /// @custom:oz-upgrades-unsafe-allow state-variable-immutable\n    address private immutable _trustedForwarder;\n\n    /// @custom:oz-upgrades-unsafe-allow constructor\n    constructor(address trustedForwarder) {\n        _trustedForwarder = trustedForwarder;\n    }\n```\n\n\n## Previous Artwork\n\n- https://github.com/sambacha/audit-format\n\n\u003e**Note**    \n\u003e This is a non-exhaustive list\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsambacha%2Fdappspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsambacha%2Fdappspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsambacha%2Fdappspec/lists"}