Skip to content

N
nebula
Commit 707b0cc0 authored by Ori Pomerantz's avatar Ori Pomerantz
Browse files
Options

feat(packages/sdk): Final touches on the docs

parent dfcd8feb
Hide whitespace changes
Inline Side-by-side
Showing with 236 additions and 209 deletions
packages/atst/README.md
View file @ 707b0cc0
...@@ -16,9 +16,9 @@ ...@@ -16,9 +16,9 @@
# atst # atst
atst is a typescript sdk and cli around the attestation station atst is a typescript / javascript sdk and cli around AttestationStation
### Visit [Docs](https://community.optimism.io/docs/governance/attestation-station/) for general documentation on the attestation station! **Visit [Docs](https://community.optimism.io/docs/governance/attestation-station/) for general documentation on AttestationStation.**
## Getting started ## Getting started
...@@ -28,42 +28,50 @@ Install ...@@ -28,42 +28,50 @@ Install
npm install @eth-optimism/atst wagmi @wagmi/core ethers@5.7.0 npm install @eth-optimism/atst wagmi @wagmi/core ethers@5.7.0
``` ```
## atst typescript sdk ## atst typescript/javascript sdk
The typescript sdk provides a clean [wagmi](https://wagmi.sh/) based interface for reading and writing to the attestation station The typescript sdk provides a clean [wagmi](https://wagmi.sh/) based interface for reading and writing to AttestationStation.
### See [sdk docs](https://github.com/ethereum-optimism/optimism/blob/develop/packages/atst/docs/sdk.md) for usage instructions **See [sdk docs](https://github.com/ethereum-optimism/optimism/blob/develop/packages/atst/docs/sdk.md) for usage instructions.**
## atst cli ## atst cli
The cli provides a convenient cli for interacting with the attestation station contract The cli provides a convenient cli for interacting with the AttestationStation contract
![preview](./assets/preview.gif) ![preview](./assets/preview.gif)
## React API **See [cli docs](https://github.com/ethereum-optimism/optimism/blob/develop/packages/atst/docs/cli.md) for usage instructions.**
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. ## React API
Use `createKey` and `createValue` to convert your raw keys and values into bytes that can be used in the attestation station contract calls 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 AttestationStation.
Use `parseString`, `parseBool`, `parseAddress` and `parseNumber` to convert values returned by attestation station to their correct data type. Use `createKey` and `createValue` to convert your raw keys and values into bytes that can be used in AttestationStation contract calls
For convenience we also export the hooks here. Use `parseString`, `parseBool`, `parseAddress` and `parseNumber` to convert values returned by AttestationStation to their correct data type.
`useAttestationStationAttestation` - Reads attestations with useContractRead For convenience we also [export the hooks here](https://github.com/ethereum-optimism/optimism/blob/develop/packages/atst/src/index.ts):
- `useAttestationStationAttestation` - Reads attestations with useContractRead
- `useAttestationStationVersion` - Reads attestation version
- `useAttestationStationAttest` - Wraps useContractWrite with AttestationStation abi calling attest
- `usePrepareAttestationStationAttest` - Wraps usePrepare with AttestationStation abi calling attest
- `useAttestationStationAttestationCreatedEvent` - Wraps useContractEvents for Created events
`useAttestationStationVersion` - Reads attestation version Also some more hooks exported by the cli but these are likely the only ones you need.
`useAttestationStationAttest` - Wraps useContractWrite with attestation station abi calling attest ## Contributing
`usePrepareAttestationStationAttest` - Wraps usePrepare with attestation station abi calling attest Please see our [contributing.md](https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md). No contribution is too small.
`useAttestationStationAttestationCreatedEvent` - Wraps useContractEvents for Created events Having your contribution denied feels bad.
Please consider [opening an issue](https://github.com/ethereum-optimism/optimism/issues) before adding any new features or apis.
Also some more hooks exported by the cli but these are likely the only ones you need.
## Contributing ## Getting help
Please see our [contributing.md](docs/contributing.md). No contribution is too small. If you have any problems, these resources could help you:
Having your contribution denied feels bad. Please consider opening an issue before adding any new features or apis - [sdk documentation](https://github.com/ethereum-optimism/optimism/blob/develop/packages/atst/docs/sdk.md)
- [cli documentation](https://github.com/ethereum-optimism/optimism/blob/develop/packages/atst/docs/cli.md)
- [Optimism Discord](https://discord-gateway.optimism.io/)
- [Telegram group](https://t.me/+zwpJ8Ohqgl8yNjNh)
packages/atst/docs/cli.md
View file @ 707b0cc0
...@@ -14,10 +14,10 @@ npm install @eth-optimism/atst --global ...@@ -14,10 +14,10 @@ npm install @eth-optimism/atst --global
npx atst <command> [options] npx atst <command> [options]
``` ```
## Commands ### Commands
read read an attestation - `read` read an attestation
write write an attestation - `write` write an attestation
For more info, run any command with the `--help` flag: For more info, run any command with the `--help` flag:
...@@ -26,55 +26,46 @@ npx atst read --help ...@@ -26,55 +26,46 @@ npx atst read --help
npx atst write --help npx atst write --help
``` ```
## Options: ### General options
-h, --help Display this message - `-h`, `--help` Display help message
-v, --version Display version number - `-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 ### Read
`--creator <string> Address of the creator of the attestation` - `--creator <address>` Address of the creator of the attestation
`--about <string> Address of the subject of the attestation` - `--about <address>` Address of the subject of the attestation
`--key <string> Key of the attestation either as string or hex number` - `--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)` - `[--data-type <string>]` The DataType type `string` | `bytes` | `number` | `bool` | `address` (default: `string`)
`--rpc-url [url] Rpc url to use (default: https://mainnet.optimism.io)` - `[--rpc-url <url>]` Rpc url to use (default: `https://mainnet.optimism.io`)
`--contract [address] Contract address to read from (default: 0xEE36eaaD94d1Cc1d0eccaDb55C38bFfB6Be06C77)` - `[--contract <address>]` Contract address to read from (default: `0xEE36eaaD94d1Cc1d0eccaDb55C38bFfB6Be06C77`)
`-h, --help Display this message` - `-h`, `--help` Display help message
Example: Example:
```bash ```bash
npx atst read --key "optimist.base-uri" --about 0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5 --creator 0x60c5C9c98bcBd0b0F2fD89B24c16e533BaA8CdA3 npx atst read --key "optimist.base-uri" --about 0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5 \
--creator 0x60c5C9c98bcBd0b0F2fD89B24c16e533BaA8CdA3
``` ```
### write ### Write
- `--private-key <string>` Private key of the creator of the attestation
- `[--data-type <string>]` The DataType type `string` | `bytes` | `number` | `bool` | `address` (default: `string`)
- `--about <address>` Address of the subject of the attestation
- `--key <address>` 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
`--private-key <string> Address of the creator of the attestation` Example:
`--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 ```bash
atst write --key "optimist.base-uri" --about 0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5 --value "my attestation" --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --rpc-url http://localhost:8545 npx atst write --key "optimist.base-uri" \
atst/0.0.0 --about 0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5 \
``` --value "my attestation" \
--private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
--rpc-url http://goerli.optimism.io
```
\ No newline at end of file
packages/atst/docs/sdk.md
View file @ 707b0cc0
# atst sdk docs # AttestationStation sdk docs
Typescript sdk for interacting with the ATST based on [@wagmi/core](https://wagmi.sh/core/getting-started) 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)
## Table of content
- [Installation](#installation)
- [Basic usage](#basic-usage)
- [Setup](#setup)
- [Reading an attestation](#reading-an-attestation)
- [Reading multiple attestation](#reading-multiple-attestations)
- [Writing an attestation](#writing-an-attestation)
- [API](#api)
- [High level API](#high-level-api)
- [Low level API](#low-level-api)
- [React API](#react-api)
- [Tutorial](#tutorial)
## Installation ## Installation
Install atst and it's peer dependencies. Install atst and its peer dependencies.
npm npm
...@@ -26,212 +41,223 @@ yarn ...@@ -26,212 +41,223 @@ yarn
yarn add @eth-optimism/atst @wagmi/core ethers@5.7.0 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 **Note:** As ethers v6 is not yet stable we only support ethers v5 at this time
## Basic usage ## Basic usage
Note: all functions are fully tested. The tests are a great example to see usage examples. ### Setup
### Basic Setup atst uses `@wagmi/core` under the hood.
[See their documentation for more information](https://wagmi.sh/core/getting-started).
ATST uses `@wagmi/core` under the hood. See their documentation for more information. ```javascript
import ethers from "ethers"
const wagmiCore = await import("@wagmi/core")
const wagmiAlchemy = await import("@wagmi/core/providers/alchemy")
const wagmiChains = await import("@wagmi/core/chains")
```typescript const { chains, provider, webSocketProvider } = wagmiCore.configureChains(
import { connect, createClient } from '@wagmi/core' [wagmiChains.optimismGoerli],
import { providers, Wallet } from 'ethers' [wagmiAlchemy.alchemyProvider({ apiKey: process.env.ALCHEMY_API_KEY })],
)
const provider = new providers.JsonRpcProvider({
url: parsedOptions.rpcUrl,
headers: {
'User-Agent': '@eth-optimism/atst',
},
})
createClient({ wagmiCore.createClient({
provider, provider,
webSocketProvider
}) })
``` ```
### Reading an attestation
To read an attestation use `readString`, `readAddress`, `readNumber`, `readBool`
Use `readAttestationString` with `bytes` passed in for the types parameter to read raw bytes ### Reading an attestation
Here is an example of reading an attestation used by the optimist nft Here is an example of reading an attestation used by the optimist nft
```typescript ```javascript
import { readAttestationString } from '@eth-optimism/atst' import { readAttestation } from '@eth-optimism/atst'
const creator = '0x60c5C9c98bcBd0b0F2fD89B24c16e533BaA8CdA3' const creator = '0x60c5C9c98bcBd0b0F2fD89B24c16e533BaA8CdA3'
const about = '0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5' const about = '0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5'
const key = 'optimist.base-uri' const key = 'optimist.base-uri'
const str = await readAttestationString(creator, about, key) const str = await readAttestationString(creator, about, key)
console.log(attestation)
console.log(attestation) // https://assets.optimism.io/4a609661-6774-441f-9fdb-453fdbb89931-bucket/optimist-nft/attributes // https://assets.optimism.io/4a609661-6774-441f-9fdb-453fdbb89931-bucket/optimist-nft/attributes
``` ```
### Reading multiple Attestations ### Reading multiple attestations
If reading more than one attestation you can use readAttestations to read them with multicall If reading more than one attestation you can use [`readAttestations`](#readattestations) to read them with [multicall](https://www.npmjs.com/package/ethereum-multicall).
### Writing an attestation ### 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) 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 ```typescript
import { prepareWriteAttestation, writeAttestation } from '@eth-optimism/sdk' import { prepareWriteAttestation, writeAttestation } from '@eth-optimism/atst'
const preparedTx = await prepareWriteAttestation(about, key, 'hello world') const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
console.log(preparedTx.gasLimit) console.log(preparedTx.gasLimit)
await writeAttestation(preparedTx) await writeAttestation(preparedTx)
``` ```
## API ## API
### ATTESTATION_STATION_ADDRESS
The deterministic deployment address for the attestation station currently deployed with create2 on Optimism and Optimism Goerli `0xEE36eaaD94d1Cc1d0eccaDb55C38bFfB6Be06C77` ### High level API
These functions are the easiest way to interact with the AttestationStation contract.
For a more detailed explanation, [see the tutorial](https://github.com/ethereum-optimism/optimism-tutorial/tree/main/ecosystem/attestation-station/using-sdk).
#### `getEvents`
Use `getEvents` to get attestation events using a provider and filters.
```typescript ```typescript
import { ATTESTATION_STATION_ADDRESS } from '@eth-optimism/atst' const events = await getEvents({
creator,
about,
key,
value,
provider: new ethers.providers.JsonRpcProvider('http://localhost:8545'),
fromBlockOrBlockhash,
toBlock,
})
``` ```
### abi Set `key`, `about`, `creator`, or `value` to `null` to not filter that value.
The abi of the attestation station #### `prepareWriteAttestation`
[Prepares](https://wagmi.sh/core/actions/prepareWriteContract) an attestation to be written.
This function creates the transaction data, estimates the gas cost, etc.
```typescript ```typescript
import { abi } from '@eth-optimism/atst' const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
console.log(preparedTx.gasFee)
``` ```
### readAttestation **Return Value:** A prepared transaction, ready for [`writeAttestation`](#writeattestation).
#### `readAttestation`
[Reads](https://wagmi.sh/core/actions/readContract) and parses an attestation based on it's data type. [Reads](https://wagmi.sh/core/actions/readContract) and parses an attestation based on its data type.
```typescript ```typescript
const attestation = await readAttestation( const attestation = await readAttestation(
/** creator, // Address: The creator of the attestation
* Address: The creator of the attestation about, // Address: The about topic of the attestation
*/ key, // string: The key of the attestation
creator, dataType, // Optional, the data type of the attestation, 'string' | 'bytes' | 'number' | 'bool' | 'address'
/** contractAddress // Optional address: the contract address of AttestationStation
* 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. **Return Value:** The value attested by the `creator` on the `about` address concerning the `key`, when interpreted as the `dataType`.
If there is no such attestation the result is zero, `false`, or an empty string.
### readAttestations #### `readAttestations`
Similar to read attestation but reads multiple attestations at once. Pass in a variadic amount of attestations to read. Similar to `readAttestation` but reads multiple attestations at once.
Pass in a variadic amount of attestations to read.
The parameters are all the same structure type, the one shown below.
```typescript ```typescript
const attestation = await readAttestations({ const attestationList = await readAttestations({
/** creator: <creator address>,
* Address: The creator of the attestation about: <about address>,
*/ key: <attestation key (string)>,
creator, [dataType: <data type - 'string' | 'bytes' | 'number' | 'bool' | 'address'>,]
/** [contractAddress: <contract address, if not the default>]
* 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,
})
``` ```
### Parsing bytes **Return Value:** A list of values attested by the `creator` on the `about` address concerning the `key`, when interpreted as the `dataType`.
These utilities for parsing bytes are provided:
`parseAddress` #### `writeAttestation`
`parseNumber`
`parseBool`
`parseString`
Note: `readAttestation` and `readAttestations` already parse the bytes so this is only necessary if reading attestations directly from chain instead of through this utility [Writes the prepared tx](https://wagmi.sh/core/actions/writeContract).
```typescript ```typescript
const attestation = parseAttestationBytes( const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
/** await writeAttestation(preparedTx)
* HexString: The raw bytes returned from reading an attestation ```
*/
bytes, ### Low level API
/**
* 'string' | 'bytes' | 'number' | 'bool' | 'address' These definitions allow you to communicate with AttestationStation, but are not as easy to use as the high level API.
* The data type of the attestation
* @defaults defaults to 'string' #### `ATTESTATION_STATION_ADDRESS`
*/
dataType
) The deployment address for AttestationStation currently deployed with create2 on Optimism and Optimism Goerli `0xEE36eaaD94d1Cc1d0eccaDb55C38bFfB6Be06C77`.
```typescript
import { ATTESTATION_STATION_ADDRESS } from '@eth-optimism/atst'
``` ```
### attestation keys #### `abi`
Attestation keys are limited to 32 bytes. To support keys longer than 32 bytes, you can use the `createKey` function The abi of the AttestationStation contract
```typescript
import { abi } from '@eth-optimism/atst'
```
#### `createKey`
`createKey` hashes keys longer than 31 bytes, because the atst key size is limited to 32 bytes.
```typescript ```typescript
const key = await createKey( const key = await createKey(
about,
key,
'i.am.a.key.much.longer.than.32.bytes.long' 'i.am.a.key.much.longer.than.32.bytes.long'
) )
await writeAttestation(preparedTx)
``` ```
createKey will keep the key as is if it is shorter than 32 bytes and otherwise run it through kekkak256 createKey will keep the key as is if it is shorter than 32 bytes and otherwise run it through keccak256.
### prepareWriteAttestation
[Prepares](https://wagmi.sh/core/actions/prepareWriteContract) an attestation to be written. #### `parseAddress`
```typescript Turn bytes into an address.
const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
console.log(preparedTx.gasFee)
```
### stringifyAttestationBytes **Note:** `readAttestation` and `readAttestations` already do this for you.
This is only needed if talking to the contracts directly, or through a different library.
Stringifys an attestation into raw bytes. #### `parseBool`
Turn bytes into a boolean value.
**Note:** `readAttestation` and `readAttestations` already do this for you.
This is only needed if talking to the contracts directly, or through a different library.
#### `parseNumber`
Note: `writeAttestation` already does this for you so this is only needed if using a library other than the attestation station Turn bytes into a number.
**Note:** `readAttestation` and `readAttestations` already do this for you.
This is only needed if talking to the contracts directly, or through a different library.
#### `parseString`
Turn bytes into a string.
**Note:** `readAttestation` and `readAttestations` already do this for you.
This is only needed if talking to the contracts directly, or through a different library.
#### `stringifyAttestationBytes`
Stringifys an attestation into raw bytes.
```typescript ```typescript
const stringAttestatoin = stringifyAttestationBytes('hello world') const stringAttestation = stringifyAttestationBytes('hello world')
const numberAttestation = stringifyAttestationBytes(500) const numberAttestation = stringifyAttestationBytes(500)
const hexAttestation = stringifyAttestationBytes('0x1') const hexAttestation = stringifyAttestationBytes('0x1')
const bigNumberAttestation = stringifyAttestationBytes( const bigNumberAttestation = stringifyAttestationBytes(
...@@ -239,33 +265,25 @@ const bigNumberAttestation = stringifyAttestationBytes( ...@@ -239,33 +265,25 @@ const bigNumberAttestation = stringifyAttestationBytes(
) )
``` ```
### writeAttestation **Note:** `writeAttestation` already does this for you so this is only needed if using a library other than `atst`.
[Writes the prepared tx](https://wagmi.sh/core/actions/writeContract) ### React API
```typescript 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 AttestationStation.
const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
await writeAttestation(preparedTx)
```
### getEvents Use `createKey` and `createValue` to convert your raw keys and values into bytes that can be used in AttestationStation contract calls.
Use `parseString`, `parseBool`, `parseAddress` and `parseNumber` to convert values returned by AttestationStation to their correct data type.
To getEvents use getEvents with a provider and any filters to filter the event For convenience we also [export the hooks here](../src/react.ts):
- `useAttestationStationAttestation` - Reads attestations with useContractRead
- `useAttestationStationVersion` - Reads attestation version
- `useAttestationStationAttest` - Wraps useContractWrite with AttestationStation abi calling attest
- `usePrepareAttestationStationAttest` - Wraps usePrepare with AttestationStation abi calling attest
- `useAttestationStationAttestationCreatedEvent` - Wraps useContractEvents for Created events
```typescript
const events = await getEvents({
creator,
about,
key,
value,
provider: new ethers.providers.JsonRpcProvider('http://localhost:8545'),
fromBlockOrBlockhash,
toBlock,
})
```
Set key, about, creator, or value to `null` to not include that filter
## Tutorial ## Tutorial
For a tutorial on using the attestation station in general, see out tutorial as well as other Optimism related tutorials in our [optimism-tutorial](https://github.com/ethereum-optimism/optimism-tutorial/tree/main/ecosystem/attestation-station#key-values) repo - [General atst tutorial](https://github.com/ethereum-optimism/optimism-tutorial/tree/main/ecosystem/attestation-station).
- [React atst starter](https://github.com/ethereum-optimism/optimism-starter).
packages/atst/package.json
View file @ 707b0cc0
...@@ -59,5 +59,15 @@ ...@@ -59,5 +59,15 @@
"@wagmi/core": "^0.9.2", "@wagmi/core": "^0.9.2",
"@wagmi/cli": "~0.1.5", "@wagmi/cli": "~0.1.5",
"wagmi": "~0.11.0" "wagmi": "~0.11.0"
} },
"keywords": [
"react",
"hooks",
"eth",
"ethereum",
"dapps",
"web3",
"optimism",
"attestation"
]
} }
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment