Merge pull request #4991 from ethereum-optimism/02-26-add_react_hooks

feat(atst): Add react hooks to the sdk

.changeset/twenty-wasps-think.md

+---
+'@eth-optimism/atst': patch
+---
+
+Release ATST
+

packages/atst/README.md

-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/35039927/218812217-92f0f784-cb85-43b9-9ca6-e2b9effd9eb2.png">
-    <img alt="wagmi logo" src="https://user-images.githubusercontent.com/35039927/218812217-92f0f784-cb85-43b9-9ca6-e2b9effd9eb2.png" width="auto" height="300">
-  </picture>
-</p>
+<div align="center">
+  <br />
+  <br />
+  <a href="https://optimism.io"><img alt="Optimism" src="https://raw.githubusercontent.com/ethereum-optimism/brand-kit/main/assets/svg/OPTIMISM-R.svg" width=600></a>
+  <br />
+  <h3>@eth-optimism/atst</h3> The official SDK and cli for Optimism's attestation Station
+  <br />
+</div>
 
 <p align="center">
-  I need a tagline here
+
 <p>
 <a href="https://www.npmjs.com/package/@eth-optimism/atst" target="\_parent">
 <img alt="" src="https://img.shields.io/npm/dm/@eth-optimism/atst.svg" />
@@ -14,40 +16,40 @@
 
 # atst
 
-atst is a typescript sdk and cli around the attestation station (TODO link to attstation station)
-
-Maybe put a gif of the cli here?
-
-## Visit [Docs](https://evmts-docs-fx6udvub5-evmts.vercel.app/en/getting-started) for more documentation on teh attestation station!
-
-TODO link to oris docs here
+atst is a typescript sdk and cli around the attestation station
 
-Maybe link to cli docs and sdk docs seperately?
+### Visit [Docs](https://community.optimism.io/docs/governance/attestation-station/) for general documentation on the attestation station!
 
 ## Getting started
 
 Install
 
 ```bash
-npm install @eth-optimism/atst
+npm install @eth-optimism/atst wagmi @wagmi/core ethers@5.7.0
 ```
 
-## ATST SDK
+## atst typescript sdk
 
-TODO
+The typescript sdk provides a clean [wagmi](https://wagmi.sh/) based interface for reading and writing to the attestation station
 
-## ATST CLI
+### See [sdk docs]() for usage instructions
 
-TODO
+## atst cli
 
-## Contributing
+The cli provides a convenient cli for interacting with the attestation station contract
+
+TODO put a gif here of using it
+
+## React instructions
 
-Please see our [contributing.md](/docs/contributing.md).
+For react hooks we recomend using the [wagmi cli](https://wagmi.sh/cli/getting-started) with the [etherscan plugin](https://wagmi.sh/cli/plugins/etherscan) and [react plugin](https://wagmi.sh/cli/plugins/react) to automatically generate react hooks around the attestation station. See [example/react](http://todo.todo.todo) for an example.
 
-## 🚧 WARNING: UNDER CONSTRUCTION 🚧
+Use `parseAttestationBytes` and `stringifyAttestationBytes` to parse and stringify attestations before passing them into wagmi hooks.
+
+## Contributing
 
-**This sdk is not yet released**
+Please see our [contributing.md](/docs/contributing.md). No contribution is too small.
 
-## Check out these other awesome attestation station tools
+Having your contribution denied feels bad. Please consider opening an issue before adding any new features or apis
 
-TODO
\ No newline at end of file
+## Check [Awesome ATST](https://todo.todo.todo) for awesome tools and examples around the attestation station

packages/atst/contributing.md

-# @eth-optimism/atst (WIP)
-
-TODO
-
-WIP sdk and cli tool for the attestation station. Currently in design phase. Any code here is purely experimental proof of concepts.
-
-## Dev setup
-
-To be able to run the cli commands with npx you must first link the node module so npm treats it like an installed package
-
-```
-npm link
-```
-
-Alternatively `yarn dev` will run the cli
-
-```bash
-# these are the same
-npx atst --help
-yarn dev --help
-```
-
-Example of how to read an attestation
-
-```bash
-npx atst read --key "optimist.base-uri" --about 0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5 --creator 0x60c5C9c98bcBd0b0F2fD89B24c16e533BaA8CdA3
-```

packages/atst/docs/cli.md

+# atst cli docs
+
+## Installation
+
+```bash
+npm install @eth-optimism/atst --global
+```
+
+## Usage
+
+```bash
+npx atst <command> [options]
+```
+
+## Commands
+
+read read an attestation
+write write an attestation
+
+For more info, run any command with the `--help` flag:
+
+```bash
+npx atst read --help
+npx atst write --help
+```
+
+## Options:
+
+-h, --help Display this message
+-v, --version Display version number
+
+## Usage:
+
+```bash
+npx atst <command> [options]
+```
+
+Commands:
+read read an attestation
+write write an attestation
+
+For more info, run any command with the `--help` flag:
+
+```bash
+npx atst read --help
+npx atst write --help
+```
+
+### Read
+
+`--creator <string> Address of the creator of the attestation`
+`--about <string> Address of the subject of the attestation`
+`--key <string> Key of the attestation either as string or hex number`
+`--data-type [string] Zod validator for the DataType type string | bytes | number | bool | address (default: string)`
+`--rpc-url [url] Rpc url to use (default: https://mainnet.optimism.io)`
+`--contract [address] Contract address to read from (default: 0xEE36eaaD94d1Cc1d0eccaDb55C38bFfB6Be06C77)`
+`-h, --help Display this message`
+
+Example:
+
+```bash
+npx atst read --key "optimist.base-uri" --about 0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5 --creator 0x60c5C9c98bcBd0b0F2fD89B24c16e533BaA8CdA3
+```
+
+### write
+
+`--private-key <string> Address of the creator of the attestation`
+`--data-type [string] Zod validator for the DataType type string | bytes | number | bool | address (default: string)`
+`--about <string> Address of the subject of the attestation`
+`--key <string> Key of the attestation either as string or hex number`
+`--value <string> undefined`
+`--rpc-url [url] Rpc url to use (default: https://mainnet.optimism.io)`
+`--contract [address] Contract address to read from (default: 0xEE36eaaD94d1Cc1d0eccaDb55C38bFfB6Be06C77) -h, --help Display this message`
+
+```bash
+atst write --key "optimist.base-uri" --about 0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5 --value "my attestation" --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --rpc-url http://localhost:8545
+atst/0.0.0
+```

packages/atst/docs/sdk.md

+# atst sdk docs
+
+Typescript sdk for interacting with the ATST based on [@wagmi/core](https://wagmi.sh/core/getting-started)
+
+TODO add a table of contents like [zod](https://github.com/colinhacks/zod/blob/master/README.md)
+
+## Installation
+
+Install atst and it's peer dependencies.
+
+npm
+
+```bash
+npm i @eth-optimism/atst @wagmi/core ethers@5.7.0
+```
+
+pnpm
+
+```bash
+pnpm i @eth-optimism/atst @wagmi/core ethers@5.7.0
+```
+
+yarn
+
+```bash
+yarn add @eth-optimism/atst @wagmi/core ethers@5.7.0
+```
+
+**Note** as ethers v6 is not yet stable we only support ethers v5 at this time
+
+## Basic usage
+
+### Basic Setup
+
+ATST uses `@wagmi/core` under the hood. See their documentation for more information.
+
+```typescript
+import { connect, createClient } from '@wagmi/core'
+import { providers, Wallet } from 'ethers'
+
+const provider = new providers.JsonRpcProvider({
+  url: parsedOptions.rpcUrl,
+  headers: {
+    'User-Agent': '@eth-optimism/atst',
+  },
+})
+
+createClient({
+  provider,
+})
+```
+
+### Reading an attestation
+
+Here is an example of reading an attestation used by the optimist nft
+
+```typescript
+import { readAttestation } from '@eth-optimism/atst'
+
+const creator = '0x60c5C9c98bcBd0b0F2fD89B24c16e533BaA8CdA3'
+const about = '0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5'
+const key = 'optimist.base-uri'
+const dataType = 'string' // note string is default
+
+const attestation = await readAttestation(creator, about, key, dataType)
+
+console.log(attestation) // https://assets.optimism.io/4a609661-6774-441f-9fdb-453fdbb89931-bucket/optimist-nft/attributes
+```
+
+If reading more than one attestation you can use readAttestations to read them with multicall
+
+### Writing an attestation
+
+To write to an attestation you must [connect](https://wagmi.sh/core/connectors/metaMask) your wagmi client if not already connected. If using Node.js use the [mock connector](https://wagmi.sh/core/connectors/mock)
+
+```typescript
+import { prepareWriteAttestation, writeAttestation } from '@eth-optimism/sdk'
+
+const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
+
+console.log(preparedTx.gasLimit)
+
+await writeAttestation(preparedTx)
+```
+
+## API
+
+### ATTESTATION_STATION_ADDRESS
+
+The deterministic deployment address for the attestation station currently deployed with create2 on Optimism and Optimism Goerli `0xEE36eaaD94d1Cc1d0eccaDb55C38bFfB6Be06C77`
+
+```typescript
+import { ATTESTATION_STATION_ADDRESS } from '@eth-optimism/atst'
+```
+
+### abi
+
+The abi of the attestation station
+
+```typescript
+import { abi } from '@eth-optimism/atst'
+```
+
+### readAttestation
+
+[Reads](https://wagmi.sh/core/actions/readContract) and parses an attestation based on it's data type.
+
+```typescript
+const attestation = await readAttestation(
+  /**
+   * Address: The creator of the attestation
+   */
+  creator,
+  /**
+   * Address: The about topic of the attestation
+   */
+  about,
+  /**
+   * string: The key of the attestation
+   */
+  key,
+  /**
+   * 'string' | 'bytes' | 'number' | 'bool' | 'address'
+   * The data type of the attestation
+   * @defaults defaults to 'string'
+   */
+  dataType,
+  /**
+   * Address: the contract address of the attestation station
+   * @defaults defaults to the create2 address
+   */
+  contractAddress
+)
+```
+
+`Return Value` The data returned from invoking the contract method.
+
+### readAttestations
+
+Similar to read attestation but reads multiple attestations at once. Pass in a variadic amount of attestations to read.
+
+```typescript
+const attestation = await readAttestations({
+  /**
+   * Address: The creator of the attestation
+   */
+  creator,
+  /**
+   * Address: The about topic of the attestation
+   */
+  about,
+  /**
+   * string: The key of the attestation
+   */
+  key,
+  /**
+   * 'string' | 'bytes' | 'number' | 'bool' | 'address'
+   * The data type of the attestation
+   * @defaults defaults to 'string'
+   */
+  dataType,
+  /**
+   * Address: the contract address of the attestation station
+   * @defaults defaults to the create2 address
+   */
+  contractAddress,
+  /**
+   * Boolean: Whether to allow some of the calls to fail
+   * Defaults to false
+   */
+  allowFailures,
+})
+```
+
+### parseAttestationBytes
+
+Parses raw bytes from the attestation station based on the type.
+
+Note: `readAttestation` and `readAttestations` already parse the bytes so this is only necessary if reading attestations directly from chain instead of through this sdkA
+
+```typescript
+const attestation = parseAttestationBytes(
+  /**
+   * HexString: The raw bytes returned from reading an attestation
+   */
+  bytes,
+  /**
+   * 'string' | 'bytes' | 'number' | 'bool' | 'address'
+   * The data type of the attestation
+   * @defaults defaults to 'string'
+   */
+  dataType
+)
+```
+
+### prepareWriteAttestation
+
+[Prepares](https://wagmi.sh/core/actions/prepareWriteContract) an attestation to be written.
+
+```typescript
+const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
+console.log(preparedTx.gasFee)
+```
+
+### stringifyAttestationBytes
+
+Stringifys an attestation into raw bytes.
+
+Note: `writeAttestation` already does this for you so this is only needed if using a library other than the attestation station
+
+```typescript
+const stringAttestatoin = stringifyAttestationBytes('hello world')
+const numberAttestation = stringifyAttestationBytes(500)
+const hexAttestation = stringifyAttestationBytes('0x1')
+const bigNumberAttestation = stringifyAttestationBytes(
+  BigNumber.from('9999999999999999999999999')
+)
+```
+
+### writeAttestation
+
+[Writes the prepared tx](https://wagmi.sh/core/actions/writeContract)
+
+```typescript
+const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
+await writeAttestation(preparedTx)
+```

packages/atst/package.json

@@ -13,6 +13,7 @@
     "dev": "tsx src/cli.ts",
     "clean": "rm -rf ./node_modules && rm -rf ./dist && rm -rf ./coverage",
     "build": "yarn tsup",
+    "generate": "wagmi generate",
     "lint": "yarn lint:fix && yarn lint:check",
     "lint:check": "eslint . --max-warnings=0",
     "lint:fix": "yarn lint:check --fix",
@@ -21,16 +22,18 @@
   },
   "dependencies": {
     "cac": "^6.7.14",
-    "ethers": "^5.7.0",
     "picocolors": "^1.0.0",
     "ora": "^6.1.2",
     "zod": "^3.11.6"
   },
   "peerDependencies": {
-    "@wagmi/core": ">0.9.0"
+    "@wagmi/core": ">0.9.0",
+    "wagmi": ">0.11.0",
+    "ethers": "^5.0.0"
   },
   "devDependencies": {
     "@testing-library/react-hooks": "^8.0.1",
+    "ethers": "^5.7.0",
     "jsdom": "^21.1.0",
     "react-dom": "^18.2.0",
     "react": "^18.2.0",
@@ -39,6 +42,8 @@
     "tsup": "^6.5.0",
     "tsx": "^3.12.2",
     "typescript": "^4.9.3",
-    "@wagmi/core": "^0.9.2"
+    "@wagmi/core": "^0.9.2",
+    "@wagmi/cli": "~0.1.5",
+    "wagmi": "~0.11.0"
   }
 }

packages/atst/src/lib/stringifyAttestationBytes.ts

@@ -5,8 +5,12 @@ import { isAddress, isHexString, toUtf8Bytes } from 'ethers/lib/utils.js'
 import { WagmiBytes } from '../types/WagmiBytes'
 
 export const stringifyAttestationBytes = (
-  bytes: WagmiBytes | string | Address | number | boolean
+  bytes: WagmiBytes | string | Address | number | boolean | BigNumber
 ) => {
+  bytes = bytes === '0x' ? '0x0' : bytes
+  if (BigNumber.isBigNumber(bytes)) {
+    return bytes.toHexString()
+  }
   if (typeof bytes === 'number') {
     return BigNumber.from(bytes).toHexString()
   }

packages/atst/wagmi.config.ts

+import { defineConfig } from '@wagmi/cli'
+import { hardhat, react } from '@wagmi/cli/plugins'
+import * as chains from 'wagmi/chains'
+import {ATTESTATION_STATION_ADDRESS} from '@eth-optimism/atst'
+
+export default defineConfig({
+  out: 'src/react.ts',
+  plugins: [
+    hardhat({
+      project: '../contracts-periphery',
+      include: ['AttestationStation.json'],
+      deployments: {
+        AttestationStation: {
+          [chains.optimism.id]: ATTESTATION_STATION_ADDRESS,
+          [chains.optimismGoerli.id]: ATTESTATION_STATION_ADDRESS,
+          [chains.foundry.id]: ATTESTATION_STATION_ADDRESS,
+        }
+      },
+    }),
+    react(),
+  ],
+})