🎁 Examples (#34)

.changeset/quiet-peas-fail.md

@@ -0,0 +1,5 @@
+---
+"create-lz-oapp": patch
+---
+
+Add the ability to override the default example repository using env variables

README.md

@@ -14,11 +14,24 @@ nvm use
 
 yarn
 
+# Build the entire project
 yarn build
 
+# Lints the entire project
 yarn lint
 
+# Tests the entire project
 yarn test
+
+# Runs the project in development mode
+yarn dev
+```
+
+This project is built using `turborepo`. The above commands are just aliases to `turbo` CLI and as such support all the `turbo` options:
+
+```bash
+# To start the development mode for create-lz-oapp and its depenendencies
+yarn dev --filter=create-lz-oapp...
 ```
 
 ### Troubleshooting

examples/oft/.eslintrc.js

@@ -0,0 +1,5 @@
+require('@rushstack/eslint-patch/modern-module-resolution');
+
+module.exports = {
+    extends: ['@layerzerolabs/eslint-config-next/recommended'],
+};

examples/oft/.gitignore

@@ -0,0 +1,16 @@
+node_modules
+.env
+coverage
+coverage.json
+typechain
+typechain-types
+
+# Hardhat files
+cache
+artifacts
+
+#foundry test compilation files
+out
+
+# yarn
+yarn-error.log

examples/oft/.prettierrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+    ...require('@layerzerolabs/prettier-config-next'),
+};

examples/oft/README.md

@@ -0,0 +1,27 @@
+<p align="center">
+  <a href="https://layerzero.network">
+    <img alt="LayerZero" style="max-width: 500px" src="https://d3a2dpnnrypp5h.cloudfront.net/bridge-app/lz.png"/>
+  </a>
+</p>
+
+<h1 align="center">@layerzerolabs/oft-example</h1>
+
+## Template repository for getting started with LayerZero using either Hardhat or Foundry in one project.
+
+### Getting Started
+
+#### Using Foundry
+
+```bash
+forge install
+forge build
+forge test
+```
+
+#### Using Hardhat
+
+```bash
+yarn
+npx hardhat compile
+npx hardhat test
+```

examples/oft/contracts/YourOFT.sol

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+import { OFT } from "@layerzerolabs/lz-evm-oapp-v2/contracts/standards/oft/OFT.sol";
+
+contract YourOFT is OFT {
+    constructor(
+        string memory _name,
+        string memory _symbol,
+        uint8 _localDecimals,
+        address _endpoint
+    ) OFT(_name, _symbol, _localDecimals, _endpoint) {}
+
+    // TODO In the event you wish to add custom logic to your OFT contract, uncomment these and alter any corresponding logic...
+
+    // @dev allows the quote functions to mock sending the actual values that would be sent in a send()/sendAndCall()
+    //    function _debitView(
+    //        uint256 _amountLD,
+    //        uint256 _minAmountLD,
+    //        uint32 /*_dstEid*/
+    //    ) internal view virtual override returns (uint256) {
+    //        uint256 amountLDSend = _removeDust(_amountLD);
+    //        if (amountLDSend < _minAmountLD) revert AmountSlippage(amountLDSend, _minAmountLD);
+    //
+    //        return amountLDSend;
+    //    }
+
+    // @dev hook applied to debit tokens on the src chain
+    //    function _debit(
+    //        uint256 _amountLD,
+    //        uint256 _minAmountLD,
+    //        uint32 _dstEid
+    //    ) internal virtual override returns (uint256) {
+    //        uint256 amountLDSend = _debitView(_amountLD, _minAmountLD, _dstEid);
+    //
+    //        _burn(msg.sender, amountLDSend);
+    //        return amountLDSend;
+    //    }
+
+    // @dev hook applied on the receipt of tokens on the dst chain
+    //    function _credit(address _to, uint256 _amountLD, uint32 /*_srcEid*/) internal virtual override returns (uint256) {
+    //        _mint(_to, _amountLD);
+    //        return _amountLD;
+    //    }
+}

examples/oft/deploy/YourOFT.ts

@@ -0,0 +1,27 @@
+import { type DeployFunction } from 'hardhat-deploy/types'
+
+// TODO declare your contract name here
+const contractName = 'YourOFT'
+
+const deploy: DeployFunction = async (hre) => {
+    const { getNamedAccounts, deployments } = hre
+
+    const { deploy } = deployments
+    const { deployer } = await getNamedAccounts()
+
+    console.log(`Network: ${hre.network.name}`)
+    console.log(`Deployer: ${deployer}`)
+
+    const { address } = await deploy(contractName, {
+        from: deployer,
+        args: [],
+        log: true,
+        waitConfirmations: 3,
+        skipIfAlreadyDeployed: false,
+    })
+
+    console.log(`Deployed contract: ${contractName}, network: ${hre.network.name}, address: ${address}`)
+}
+
+module.exports.tags = [contractName]
+export default deploy

examples/oft/foundry.toml

@@ -0,0 +1,8 @@
+[profile.default]
+src = 'contracts'
+out = 'out'
+test = 'test/foundry'
+cache_path = 'cache'
+libs = ['node_modules', '../lib']
+
+# See more config options https://github.com/foundry-rs/foundry/tree/master/config

examples/oft/hardhat.config.ts

@@ -0,0 +1,18 @@
+import 'hardhat-deploy'
+import 'hardhat-contract-sizer'
+import '@nomiclabs/hardhat-ethers'
+import { HardhatUserConfig } from 'hardhat/types'
+
+import './tasks/'
+
+const config: HardhatUserConfig = {
+    solidity: '0.8.19',
+
+    namedAccounts: {
+        deployer: {
+            default: 0, // wallet address of index[0], of the mnemonic in .env
+        },
+    },
+}
+
+export default config

examples/oft/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@layerzerolabs/oft-example",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "scripts": {
+    "compile": "npx hardhat compile",
+    "lint": "yarn lint:js && yarn lint:sol",
+    "lint:fix": "npx prettier --write . && solhint 'contracts/**/*.sol' --fix --noPrompt",
+    "lint:js": "npx eslint '**/*.js' && npx prettier --check .",
+    "lint:sol": "solhint 'contracts/**/*.sol'",
+    "test": "npx hardhat test --parallel"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.23.3",
+    "@layerzerolabs/eslint-config-next": "^1.5.60",
+    "@layerzerolabs/lz-evm-oapp-v2": "latest",
+    "@layerzerolabs/prettier-config-next": "^1.5.60",
+    "@layerzerolabs/solhint-config": "^1.5.58",
+    "@nomiclabs/hardhat-ethers": "^2.2.3",
+    "@rushstack/eslint-patch": "^1.5.1",
+    "ethers": "^5.7.0",
+    "hardhat": "^2.9.9",
+    "hardhat-contract-sizer": "^2.10.0",
+    "hardhat-deploy": "^0.11.43",
+    "hardhat-deploy-ethers": "^0.4.1",
+    "prettier": "^3.0.3",
+    "solhint": "^4.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.2.2"
+  }
+}

examples/oft/solhint.config.js

@@ -0,0 +1 @@
+module.exports = require('@layerzerolabs/solhint-config');

examples/oft/tasks/getSigners.ts

@@ -0,0 +1,21 @@
+import { task, types } from 'hardhat/config'
+import { type ActionType } from 'hardhat/types'
+
+// TODO Figure out a way so this doesnt need to be defined in two places
+interface TaskArguments {
+    n: number
+}
+
+const action: ActionType<TaskArguments> = async (taskArgs, hre) => {
+    const signers = await hre.ethers.getSigners()
+    for (let i = 0; i < taskArgs.n; ++i) {
+        console.log(`${i}) ${signers[i].address}`)
+    }
+}
+
+task('getSigners', 'show the signers of the current mnemonic', action).addOptionalParam(
+    'n',
+    'how many to show',
+    3,
+    types.int
+)

examples/oft/tasks/index.ts

@@ -0,0 +1,2 @@
+import './getSigners'
+// TODO get rid of index.ts somehow so we only need to define it in one place

examples/oft/test/foundry/OFT.t.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: UNLICENSED
+
+pragma solidity ^0.8.15;
+
+import { Test } from "forge-std/Test.sol";
+
+contract YourOApp is Test {
+    function setUp() public {
+        //TODO
+    }
+
+    function test() public {
+        //TODO
+    }
+}

examples/oft/test/hardhat/OFT.test.ts

@@ -0,0 +1,13 @@
+describe.skip('OFT: ', function () {
+    before(async function () {
+        //TODO
+    })
+
+    beforeEach(async function () {
+        //TODO
+    })
+
+    it('OFT send', async function () {
+        //TODO
+    })
+})

examples/oft/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "exclude": ["node_modules"],
+  "include": ["deploy", "tasks", "hardhat.config.ts"],
+  "compilerOptions": {
+    "target": "es2020",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  }
+}

package.json

@@ -11,6 +11,7 @@
         "prepare": "husky install"
     },
     "workspaces": [
+        "examples/*",
         "packages/*"
     ],
     "devDependencies": {

packages/create-lz-oapp/.mocharc.json

@@ -0,0 +1,5 @@
+{
+    "extensions": ["ts"],
+    "spec": ["**/*.test.*"],
+    "loader": "ts-node/esm"
+}

packages/create-lz-oapp/package.json

@@ -28,7 +28,8 @@
         "dev": "npx tsup --watch",
         "lint": "npx eslint '**/*.{js,ts,json}'",
         "prebuild": "tsc -noEmit",
-        "start": "./cli.cjs"
+        "start": "./cli.cjs",
+        "test": "mocha --parallel"
     },
     "files": [
         "./cli.cjs",
@@ -40,9 +41,11 @@
     "devDependencies": {
         "@sindresorhus/tsconfig": "^5.0.0",
         "@tanstack/react-query": "^5.8.3",
+        "@types/mocha": "^10.0.1",
         "@types/prompts": "^2.4.8",
         "@types/react": "^18.0.32",
         "@types/which": "~3.0.2",
+        "chai": "^4.3.10",
         "commander": "^11.1.0",
         "eslint-plugin-react": "^7.32.2",
         "eslint-plugin-react-hooks": "^4.6.0",
@@ -51,6 +54,7 @@
         "ink-select-input": "^5.0.0",
         "ink-spinner": "^5.0.0",
         "ink-text-input": "^5.0.1",
+        "mocha": "^10.0.0",
         "prompts": "^2.4.2",
         "react": "^18.2.0",
         "react-devtools-core": "^4.28.5",

packages/create-lz-oapp/src/components/setup.tsx

@@ -2,7 +2,7 @@ import React, { useEffect } from "react"
 import type { Config } from "@/types.js"
 import { Box, Text } from "ink"
 import { useMutation } from "@tanstack/react-query"
-import { DestinationNotEmptyError, DownloadError, MissingGitRefError, cloneExample } from "@/utilities/cloning.js"
+import { BadGitRefError, DestinationNotEmptyError, DownloadError, MissingGitRefError, cloneExample } from "@/utilities/cloning.js"
 import { Progress } from "./progress.js"
 import { installDependencies } from "@/utilities/installation.js"
 
@@ -63,6 +63,14 @@ const ErrorMessage: React.FC<ErrorMessageProps> = ({ config, error }) => {
                 </Text>
             )
 
+        case error instanceof BadGitRefError:
+            return (
+                <Text color="red">
+                    The example <Text bold>{config.example.label}</Text> has its repository URL malformed: '
+                    <Text bold>{config.example.repository}</Text>' does not look like a valid repository
+                </Text>
+            )
+
         case error instanceof MissingGitRefError:
             return (
                 <Text color="red">