@paimaexample/evm-contracts 0.3.0

package/README.md

@@ -0,0 +1,7 @@
+# Paima EVM contracts
+
+NPM package for EVM contracts for Paima Engine and related utilities.
+
+See
+[the Paima documentation](https://docs.paimastudios.com/home/libraries/evm-contracts/introduction)
+for full documentation.

package/deno.json

@@ -0,0 +1,28 @@
+{
+  "name": "@paima/evm-contracts",
+  "version": "0.3.0",
+  "license": "MIT",
+  "exports": "./mod.ts",
+  "imports": {
+    "@wagmi/cli": "npm:@wagmi/cli@2.3.1",
+    "hardhat": "npm:hardhat@3.0.0-next.20",
+    "@nomicfoundation/hardhat-ignition": "npm:@nomicfoundation/hardhat-ignition@3.0.0-next.20",
+    "@nomicfoundation/hardhat-viem": "npm:@nomicfoundation/hardhat-viem@3.0.0-next.20"
+  },
+  "tasks": {
+    // deno doesn't support installing packages from Github (https://github.com/denoland/deno/issues/18478)
+    // we can't easily use file: dependency as that isn't supported either (https://github.com/denoland/deno/issues/18474)
+    // so instead we symlink to a local copy of the project
+    "link:forge": "bash -c 'if ! [ -L ../../../../node_modules/forge-std ]; then ln -s ../forge-std ../../../../node_modules/forge-std; fi'",
+    // TODO: update `hardhat docgen` to Hardhat v3
+    // note: this should be `deno run hardhat3 compile`, but Deno doesn't like that so we have to use the full name
+    "build:contracts": "forge build && deno run -A npm:hardhat@3.0.0-next.3 compile",
+    "build:publish": "deno run -A prepare.ts",
+    "prebuild": "rm -rf ./build",
+    "build": "deno task prebuild && deno task build:contracts && deno task build:publish",
+    "clean": "rm -rf ./artifacts && rm -rf ./cache && rm -rf ./build",
+    "test": "forge test",
+    // TODO: how to integrate Prettier plugin with deno and/or forge?
+    "prettier": "prettier --write '**/*.{sol,js,ts}' --ignore-path .gitignore"
+  }
+}

package/docs/templates/contract.hbs

@@ -0,0 +1,144 @@
+<ContractHeader githubLink="https://github.com/PaimaStudios/paima-engine/tree/master/packages/contracts/evm-contracts/{{__item_context.file.absolutePath}}" anchor="{{~anchor~}}">
+    ### {{name}}
+</ContractHeader>
+
+```solidity
+import "@paima/evm-contracts/{{__item_context.file.absolutePath}}";
+```
+
+{{{natspec.dev}}}
+
+{{#if modifiers}}
+<SolidityOutlineBlock
+  type="Modifiers"
+  lists={[
+    {
+      category: "",
+      lines: [
+        {{#each modifiers}}
+        {
+          text: "{{name}}({{names params}})",
+          anchor: "xref-{{anchor~}}"
+        },
+        {{/each}}
+      ]
+    }
+  ]}
+>
+</SolidityOutlineBlock>
+{{/if}}
+
+{{#if has-functions}}
+<SolidityOutlineBlock
+  type="Functions"
+  lists={[
+    {{#each inherited-functions}}
+    {
+      category: "{{#unless @first}}{{contract.name}}{{/unless}}",
+      lines: [
+        {{#each functions}}
+        {
+          text: "{{name}}({{names params}})",
+          anchor: "xref-{{anchor~}}"
+        },
+        {{/each}}
+      ]
+    },
+    {{/each}}
+  ]}
+>
+</SolidityOutlineBlock>
+{{/if}}
+
+{{#if has-events}}
+<SolidityOutlineBlock
+  type="Events"
+  lists={[
+    {{#each inheritance}}
+    {
+      category: "{{#unless @first}}{{name}}{{/unless}}",
+      lines: [
+        {{#each events}}
+        {
+          text: "{{name}}({{names params}})",
+          anchor: "xref-{{anchor~}}"
+        },
+        {{/each}}
+      ]
+    },
+    {{/each}}
+  ]}
+>
+</SolidityOutlineBlock>
+{{/if}}
+
+{{#if has-errors}}
+<SolidityOutlineBlock
+  type="Errors"
+  lists={[
+    {{#each inheritance}}
+    {
+      category: "{{#unless @first}}{{name}}{{/unless}}",
+      lines: [
+        {{#each errors}}
+        {
+          text: "{{name}}({{names params}})",
+          anchor: "xref-{{anchor~}}"
+        },
+        {{/each}}
+      ]
+    },
+    {{/each}}
+  ]}
+>
+</SolidityOutlineBlock>
+{{/if}}
+
+
+{{#each modifiers}}
+<SolidityDetailBlock
+    title="{{name}}"
+    params="({{typed-params params}})"
+    visibility="modifier"
+    anchor="xref-{{anchor}}"
+>
+    {{{escapeChars natspec.dev}}}
+</SolidityDetailBlock>
+
+{{/each}}
+
+{{#each functions}}
+<SolidityDetailBlock
+    title="{{name}}"
+    params="({{typed-params params}}){{#if returns2}} → {{typed-params returns2}}{{/if}}"
+    visibility="{{visibility}}"
+    anchor="xref-{{anchor}}"
+>
+    {{{escapeChars natspec.dev}}}
+</SolidityDetailBlock>
+
+{{/each}}
+
+{{#each events}}
+<SolidityDetailBlock
+    title="{{name}}"
+    params="({{typed-params params}})"
+    visibility="event"
+    anchor="xref-{{anchor}}"
+>
+    {{{escapeChars natspec.dev}}}
+</SolidityDetailBlock>
+
+{{/each}}
+
+{{#each errors}}
+<SolidityDetailBlock
+    title="{{name}}"
+    params="({{typed-params params}})"
+    visibility="error"
+    anchor="xref-{{anchor}}"
+>
+    {{{escapeChars natspec.dev}}}
+</SolidityDetailBlock>
+
+{{/each}}

package/docs/templates/helpers.js

@@ -0,0 +1,61 @@
+const { version } = require("../../package.json");
+
+module.exports["escapeChars"] = (input) => {
+  if (input == null) return "No description given";
+  // escape the curly braces (replace them with \{ )
+  // useful to escape cases like {IERC721Receiver-onERC721Received}
+  return input.replace(/\{([a-zA-Z0-9_-]+)\}/g, "\\{$1\\}");
+};
+
+module.exports["oz-version"] = () => version;
+
+module.exports["readme-path"] = (opts) => {
+  return "contracts/" + opts.data.root.id.replace(/\.mdx?$/, "") + "/README.md";
+};
+
+module.exports.names = (params) => params?.map((p) => p.name).join(", ");
+
+module.exports["typed-params"] = (params) => {
+  return params
+    ?.map((p) =>
+      `${p.type}${p.indexed ? " indexed" : ""}${p.name ? " " + p.name : ""}`
+    )
+    .join(", ");
+};
+
+const slug = (module.exports.slug = (str) => {
+  if (str === undefined) {
+    throw new Error("Missing argument");
+  }
+  return str.replace(/\W/g, "-");
+});
+
+const linksCache = new WeakMap();
+
+function getAllLinks(items) {
+  if (linksCache.has(items)) {
+    return linksCache.get(items);
+  }
+  const res = {};
+  linksCache.set(items, res);
+  for (const item of items) {
+    res[`xref-${item.anchor}`] =
+      `xref:${item.__item_context.page}#${item.anchor}`;
+    res[slug(item.fullName)] =
+      `pass:normal[xref:${item.__item_context.page}#${item.anchor}[\`${item.fullName}\`]]`;
+  }
+  return res;
+}
+
+module.exports["with-prelude"] = (opts) => {
+  const contents = opts.fn();
+  // generate table of contents
+  // const links = getAllLinks(opts.data.site.items);
+  // const neededLinks = contents
+  //   .match(/\[[-._a-z0-9]+\]/gi)
+  //   .map(m => m.replace(/^\[(.+)\]$/, '$1'))
+  //   .filter(k => k in links);
+  // const prelude = neededLinks.map(k => `- [${k}](#${k})`).join('\n');
+  return contents;
+  // return prelude + '\n' + contents;
+};

package/docs/templates/page.hbs

@@ -0,0 +1,7 @@
+import SolidityDetailBlock from '@site/src/components/SolidityDetailBlock';
+import SolidityOutlineBlock from '@site/src/components/SolidityOutlineBlock';
+import ContractHeader from '@site/src/components/ContractHeader';
+
+{{#with-prelude}}
+{{readme (readme-path)}}
+{{/with-prelude}}

package/docs/templates/properties.js

@@ -0,0 +1,76 @@
+const { isNodeType, findAll } = require("solidity-ast/utils");
+const { slug } = require("./helpers");
+
+module.exports.anchor = function anchor({ item, contract }) {
+  let res = "";
+  if (contract) {
+    res += contract.name + "-";
+  }
+  res += item.name;
+  if ("parameters" in item) {
+    const signature = item.parameters.parameters
+      .map((v) => v.typeName.typeDescriptions.typeString)
+      .join(",");
+    res += slug("(" + signature + ")");
+  }
+  if (isNodeType("VariableDeclaration", item)) {
+    res += "-" + slug(item.typeName.typeDescriptions.typeString);
+  }
+  return res;
+};
+
+module.exports.inheritance = function ({ item, build }) {
+  if (!isNodeType("ContractDefinition", item)) {
+    throw new Error("used inherited-items on non-contract");
+  }
+
+  return item.linearizedBaseContracts
+    .map((id) => build.deref("ContractDefinition", id))
+    .filter((c, i) => c.name !== "Context" || i === 0);
+};
+
+module.exports["has-functions"] = function ({ item }) {
+  return item.inheritance.some((c) => c.functions.length > 0);
+};
+
+module.exports["has-events"] = function ({ item }) {
+  return item.inheritance.some((c) => c.events.length > 0);
+};
+
+module.exports["has-errors"] = function ({ item }) {
+  return item.inheritance.some((c) => c.errors.length > 0);
+};
+
+module.exports.functions = function ({ item }) {
+  return [
+    ...[...findAll("FunctionDefinition", item)].filter((f) =>
+      f.visibility !== "private"
+    ),
+    ...[...findAll("VariableDeclaration", item)].filter((f) =>
+      f.visibility === "public"
+    ),
+  ];
+};
+
+module.exports.returns2 = function ({ item }) {
+  if (isNodeType("VariableDeclaration", item)) {
+    return [{ type: item.typeDescriptions.typeString }];
+  } else {
+    return item.returns;
+  }
+};
+
+module.exports["inherited-functions"] = function ({ item }) {
+  const { inheritance } = item;
+  const baseFunctions = new Set(
+    inheritance.flatMap((c) =>
+      c.functions.flatMap((f) => f.baseFunctions ?? [])
+    ),
+  );
+  return inheritance.map((contract, i) => ({
+    contract,
+    functions: contract.functions.filter(
+      (f) => !baseFunctions.has(f.id) && (f.name !== "constructor" || i === 0),
+    ),
+  }));
+};

package/hardhat.config.ts

@@ -0,0 +1,11 @@
+import type { HardhatUserConfig } from "hardhat/config";
+
+import { defaultHardhatConfig } from "./src/recommendedHardhat.ts";
+
+const config: HardhatUserConfig = {
+  ...defaultHardhatConfig({
+    outDir: "./build",
+  }),
+};
+
+export default config;

package/index.js

@@ -0,0 +1 @@
+// Empty entry point for the npm package.

package/package.json

@@ -0,0 +1,13 @@
+{
+  "type": "module",
+  "dependencies": {
+    "@openzeppelin/contracts": "5.1.0",
+    "@openzeppelin/contracts-upgradeable": "^5.1.0"
+  },
+  "name": "@paimaexample/evm-contracts",
+  "version": "0.3.0",
+  "description": "Paima EVM default contracts.",
+  "main": "index.js",
+  "author": "Paima Studios",
+  "license": "MIT"
+}

package/remappings.txt

@@ -0,0 +1 @@
+@openzeppelin/=node_modules/@openzeppelin/

package/src/companions/ERC165Contract.json

@@ -0,0 +1,21 @@
+[
+  {
+    "inputs": [
+      {
+        "internalType": "bytes4",
+        "name": "interfaceId",
+        "type": "bytes4"
+      }
+    ],
+    "name": "supportsInterface",
+    "outputs": [
+      {
+        "internalType": "bool",
+        "name": "",
+        "type": "bool"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  }
+]

package/src/companions/ERC165Contract.ts

@@ -0,0 +1,21 @@
+export default [
+  {
+    inputs: [
+      {
+        internalType: "bytes4",
+        name: "interfaceId",
+        type: "bytes4",
+      },
+    ],
+    name: "supportsInterface",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "",
+        type: "bool",
+      },
+    ],
+    stateMutability: "view",
+    type: "function",
+  },
+] as const;

package/src/companions/ERC20Contract.json

@@ -0,0 +1,222 @@
+[
+  {
+    "constant": true,
+    "inputs": [],
+    "name": "name",
+    "outputs": [
+      {
+        "name": "",
+        "type": "string"
+      }
+    ],
+    "payable": false,
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "constant": false,
+    "inputs": [
+      {
+        "name": "_spender",
+        "type": "address"
+      },
+      {
+        "name": "_value",
+        "type": "uint256"
+      }
+    ],
+    "name": "approve",
+    "outputs": [
+      {
+        "name": "",
+        "type": "bool"
+      }
+    ],
+    "payable": false,
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "constant": true,
+    "inputs": [],
+    "name": "totalSupply",
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint256"
+      }
+    ],
+    "payable": false,
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "constant": false,
+    "inputs": [
+      {
+        "name": "_from",
+        "type": "address"
+      },
+      {
+        "name": "_to",
+        "type": "address"
+      },
+      {
+        "name": "_value",
+        "type": "uint256"
+      }
+    ],
+    "name": "transferFrom",
+    "outputs": [
+      {
+        "name": "",
+        "type": "bool"
+      }
+    ],
+    "payable": false,
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "constant": true,
+    "inputs": [],
+    "name": "decimals",
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint8"
+      }
+    ],
+    "payable": false,
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "constant": true,
+    "inputs": [
+      {
+        "name": "_owner",
+        "type": "address"
+      }
+    ],
+    "name": "balanceOf",
+    "outputs": [
+      {
+        "name": "balance",
+        "type": "uint256"
+      }
+    ],
+    "payable": false,
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "constant": true,
+    "inputs": [],
+    "name": "symbol",
+    "outputs": [
+      {
+        "name": "",
+        "type": "string"
+      }
+    ],
+    "payable": false,
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "constant": false,
+    "inputs": [
+      {
+        "name": "_to",
+        "type": "address"
+      },
+      {
+        "name": "_value",
+        "type": "uint256"
+      }
+    ],
+    "name": "transfer",
+    "outputs": [
+      {
+        "name": "",
+        "type": "bool"
+      }
+    ],
+    "payable": false,
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "constant": true,
+    "inputs": [
+      {
+        "name": "_owner",
+        "type": "address"
+      },
+      {
+        "name": "_spender",
+        "type": "address"
+      }
+    ],
+    "name": "allowance",
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint256"
+      }
+    ],
+    "payable": false,
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "payable": true,
+    "stateMutability": "payable",
+    "type": "fallback"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "name": "owner",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "name": "spender",
+        "type": "address"
+      },
+      {
+        "indexed": false,
+        "name": "value",
+        "type": "uint256"
+      }
+    ],
+    "name": "Approval",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "name": "from",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "name": "to",
+        "type": "address"
+      },
+      {
+        "indexed": false,
+        "name": "value",
+        "type": "uint256"
+      }
+    ],
+    "name": "Transfer",
+    "type": "event"
+  }
+]