Skip to content

N
nebula
Commit a71e1dbc authored by mergify[bot]'s avatar mergify[bot] Committed by GitHub
Browse files
Options

Merge branch 'develop' into sc/fd-correct-length

parents f9b579d5 b0f4c978
Hide whitespace changes
Inline Side-by-side
Showing with 194 additions and 186 deletions
packages/atst/docs/cli.md
View file @ a71e1dbc
......@@ -14,10 +14,10 @@ npm install @eth-optimism/atst --global
npx atst <command> [options]
```
## Commands
### Commands
read read an attestation
write write an attestation
- `read` read an attestation
- `write` write an attestation
For more info, run any command with the `--help` flag:
......@@ -26,55 +26,46 @@ npx atst read --help
npx atst write --help
```
## Options:
### General options
-h, --help Display this message
-v, --version Display version number
- `-h`, `--help` Display help 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`
- `--creator <address>` Address of the creator of the attestation
- `--about <address>` Address of the subject of the attestation
- `--key <string>` Key of the attestation either as string or hex number
- `[--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`)
- `[--contract <address>]` Contract address to read from (default: `0xEE36eaaD94d1Cc1d0eccaDb55C38bFfB6Be06C77`)
- `-h`, `--help` Display help message
Example:
```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`
`--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`
Example:
```bash
atst write --key "optimist.base-uri" --about 0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5 --value "my attestation" --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --rpc-url http://localhost:8545
atst/0.0.0
atst write --key "optimist.base-uri" \
--about 0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5 \
--value "my attestation" \
--private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
--rpc-url http://localhost:8545
```
packages/atst/docs/sdk.md
View file @ a71e1dbc
......@@ -2,11 +2,26 @@
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
Install atst and it's peer dependencies.
Install atst and its peer dependencies.
npm
......@@ -26,212 +41,223 @@ yarn
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
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
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',
},
})
const { chains, provider, webSocketProvider } = wagmiCore.configureChains(
[wagmiChains.optimismGoerli],
[wagmiAlchemy.alchemyProvider({ apiKey: process.env.ALCHEMY_API_KEY })],
)
createClient({
wagmiCore.createClient({
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
```typescript
import { readAttestationString } from '@eth-optimism/atst'
```javascript
import { readAttestation } from '@eth-optimism/atst'
const creator = '0x60c5C9c98bcBd0b0F2fD89B24c16e533BaA8CdA3'
const about = '0x2335022c740d17c2837f9C884Bfe4fFdbf0A95D5'
const key = 'optimist.base-uri'
const str = await readAttestationString(creator, about, key)
console.log(attestation) // https://assets.optimism.io/4a609661-6774-441f-9fdb-453fdbb89931-bucket/optimist-nft/attributes
console.log(attestation)
// 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
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
import { prepareWriteAttestation, writeAttestation } from '@eth-optimism/sdk'
import { prepareWriteAttestation, writeAttestation } from '@eth-optimism/atst'
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`
### 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
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
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
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
creator, // Address: The creator of the attestation
about, // Address: The about topic of the attestation
key, // string: The key of the attestation
dataType, // Optional, the data type of the attestation, 'string' | 'bytes' | 'number' | 'bool' | 'address'
contractAddress // Optional address: the contract address of the attestation station
)
```
`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
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,
})
const attestationList = await readAttestations({
creator: <creator address>,
about: <about address>,
key: <attestation key (string)>,
[dataType: <data type - 'string' | 'bytes' | 'number' | 'bool' | 'address'>,]
[contractAddress: <contract address, if not the default>]
}, {...}, {...})
```
### 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`
`parseNumber`
`parseBool`
`parseString`
#### `writeAttestation`
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
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
)
const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
await writeAttestation(preparedTx)
```
### Low level API
These definitions allow you to communicate with AttestationStation, but are not as easy to use as the high level API.
#### `ATTESTATION_STATION_ADDRESS`
The 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'
```
### 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 attestation station 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
const key = await createKey(
about,
key,
'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
const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
console.log(preparedTx.gasFee)
```
Turn bytes into an address.
### 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
const stringAttestatoin = stringifyAttestationBytes('hello world')
const stringAttestation = stringifyAttestationBytes('hello world')
const numberAttestation = stringifyAttestationBytes(500)
const hexAttestation = stringifyAttestationBytes('0x1')
const bigNumberAttestation = stringifyAttestationBytes(
......@@ -239,33 +265,24 @@ const bigNumberAttestation = stringifyAttestationBytes(
)
```
### writeAttestation
**Note:** `writeAttestation` already does this for you so this is only needed if using a library other than the attestation station.
[Writes the prepared tx](https://wagmi.sh/core/actions/writeContract)
### React API
```typescript
const preparedTx = await prepareWriteAttestation(about, key, 'hello world')
await writeAttestation(preparedTx)
```
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.
### getEvents
Use `createKey` and `createValue` to convert your raw keys and values into bytes that can be used in the attestation station contract calls.
Use `parseString`, `parseBool`, `parseAddress` and `parseNumber` to convert values returned by attestation station 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](../src/react.ts) here:
- `useAttestationStationAttestation` - Reads attestations with useContractRead
- `useAttestationStationVersion` - Reads attestation version
- `useAttestationStationAttest` - Wraps useContractWrite with attestation station abi calling attest
- `usePrepareAttestationStationAttest` - Wraps usePrepare with attestation station 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
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
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.
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