github/semaphore
1
1
Fork 0
mirror of https://github.com/semaphore-protocol/semaphore.git synced 2026-01-10 07:08:17 -05:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation for @semaphore/data package (#768)

Browse Source 
* docs(data): improve code comments and readme of the @semaphore/data package

* docs(data): update package.json description and small nit on README
This commit is contained in:
Giacomo
2024-05-07 15:30:43 +02:00
committed by GitHub
parent 1b34ad312d
commit b9fa75cba3
9 changed files with 130 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
packages/data/README.md
View File

@@ -2,7 +2,7 @@
<h1 align="center">
Semaphore data
</h1>
<p align="center">A library to query Semaphore contracts.</p>
<p align="center">A library for querying Semaphore smart contract.</p>
</p>
<p align="center">
@@ -49,8 +49,8 @@
</h4>
</div>
| This library allows you to query the [`Semaphore.sol`](https://github.com/semaphore-protocol/semaphore/blob/main/packages/contracts/contracts/Semaphore.sol) contract data (i.e. groups) using the [Semaphore subgraph](https://github.com/semaphore-protocol/subgraph) or Ethers. It can be used on Node.js and browsers. |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| This library provides tools for querying and interacting with the [`Semaphore.sol`](https://github.com/semaphore-protocol/semaphore/blob/main/packages/contracts/contracts/Semaphore.sol) smart contract. It supports both the Semaphore subgraph and direct Ethereum network connections via Ethers. Designed for use in both Node.js and browser environments, it facilitates the management of group data and verification processes within the Semaphore protocol. |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
## 🛠 Install
@@ -70,15 +70,11 @@ yarn add @semaphore-protocol/data
## 📜 Usage
For more information on the functions provided by `@semaphore-protocol/data`, please refer to the [TypeDoc documentation](https://js.semaphore.pse.dev/modules/_semaphore_protocol_data).
For detailed information on the functions provided by `@semaphore-protocol/data`, please refer to the [TypeDoc documentation](https://js.semaphore.pse.dev/modules/_semaphore_protocol_data).
\# **getSupportedNetworks**(): _string[]_
### Creating and Managing Subgraphs
```typescript
const supportedNetworks = getSupportedNetworks()
```
\# **new SemaphoreSubgraph**(networkOrSubgraphURL: SupportedNetwork | ValueOf\<SupportedNetwork> | string = "sepolia"): _SemaphoreSubgraph_
**Initialize a Semaphore Subgraph instance**
```typescript
import { SemaphoreSubgraph } from "@semaphore-protocol/data"
@@ -86,62 +82,53 @@ import { SemaphoreSubgraph } from "@semaphore-protocol/data"
const semaphoreSubgraph = new SemaphoreSubgraph()
// or:
const semaphoreSubgraph = new SemaphoreSubgraph("arbitrum")
const semaphoreSubgraphOnArbitrum = new SemaphoreSubgraph("arbitrum")
// or:
const semaphoreSubgraph = new SemaphoreSubgraph(
const customSubgraph = new SemaphoreSubgraph(
"https://api.studio.thegraph.com/query/14377/<your-subgraph>/<your-version>"
)
```
\# **getGroupIds**(): _Promise\<string[]>_
With your SemaphoreSubgraph, you can:
**Query Group IDs**
```typescript
const groupIds = await semaphoreSubgraph.getGroupIds()
```
\# **getGroups**(options?: _GroupOptions_): _Promise\<GroupResponse[]>_
```typescript
const groups = await semaphoreSubgraph.getGroups()
// or
const groups = await semaphoreSubgraph.getGroups({ members: true, verifiedProofs: true })
```
\# **getGroup**(groupId: _string_, options?: _GroupOptions_): _Promise\<GroupResponse>_
**Query Group Details**
```typescript
const group = await semaphoreSubgraph.getGroup("42")
// or
const { members, verifiedProofs } = semaphoreSubgraph.getGroup("42", { members: true, verifiedProofs: true })
const { members, verifiedProofs } = await semaphoreSubgraph.getGroup("42", { members: true, verifiedProofs: true })
```
\# **getGroupMembers**(groupId: _string_): _Promise\<string[]>_
**Query Group Members**
```typescript
const members = await semaphoreSubgraph.getGroupMembers("42")
```
\# **getGroupVerifiedProofs**(groupId: _string_): _Promise\<any[]>_
**Query Verified Proofs**
```typescript
const verifiedProofs = await semaphoreSubgraph.getGroupVerifiedProofs("42")
```
\# **isGroupMember**(groupId: _string_, member: _string_): _Promise\<boolean>_
**Check Group Membership**
```typescript
await semaphoreSubgraph.isGroupMember(
const isMember = await semaphoreSubgraph.isGroupMember(
"42",
"16948514235341957898454876473214737047419402240398321289450170535251226167324"
)
```
\# **new Ethers**(networkOrEthereumURL: Network | string = "sepolia", options: EthersOptions = {}): _SemaphoreEthers_
### Using Ethers for Direct Blockchain Interaction
**Initialize a Semaphore Ethers instance**
```typescript
import { SemaphoreEthers } from "@semaphore-protocol/data"
@@ -149,51 +136,53 @@ import { SemaphoreEthers } from "@semaphore-protocol/data"
const semaphoreEthers = new SemaphoreEthers()
// or:
const semaphoreEthers = new SemaphoreEthers("homestead", {
const semaphoreEthersOnHomestead = new SemaphoreEthers("homestead", {
address: "semaphore-address",
startBlock: 0
})
// or:
const semaphoreEthers = new SemaphoreEthers("http://localhost:8545", {
const localEthersInstance = new SemaphoreEthers("http://localhost:8545", {
address: "semaphore-address"
})
```
\# **getGroupIds**(): _Promise\<string[]>_
With your SemaphoreEthers instance, you can:
**Fetch Group IDs**
```typescript
const groupIds = await semaphoreEthers.getGroupIds()
```
\# **getGroup**(groupId: _string_): _Promise\<GroupResponse>_
**Fetch Group Details**
```typescript
const group = await semaphoreEthers.getGroup("42")
```
\# **getGroupAdmin**(groupId: _string_): _Promise\<string>_
**Fetch Group Admin**
```typescript
const admin = await semaphoreEthers.getGroupAdmin("42")
```
\# **getGroupMembers**(groupId: _string_): _Promise\<string[]>_
**Fetch Group Members**
```typescript
const members = await semaphoreEthers.getGroupMembers("42")
```
\# **getGroupVerifiedProofs**(groupId: _string_): _Promise\<any[]>_
**Fetch Verified Proofs**
```typescript
const verifiedProofs = await semaphoreEthers.getGroupVerifiedProofs("42")
```
\# **isGroupMember**(groupId: _string_, member: _string_): _Promise\<boolean>_
**Check Group Membership**
```typescript
await semaphoreEthers.isGroupMember(
const isMember = await semaphoreEthers.isGroupMember(
"42",
"16948514235341957898454876473214737047419402240398321289450170535251226167324"
)

2
packages/data/package.json
View File

@@ -1,7 +1,7 @@
{
"name": "@semaphore-protocol/data",
"version": "4.0.0-beta.9",
"description": "A library to query Semaphore contracts.",
"description": "A library for querying Semaphore smart contract.",
"type": "module",
"license": "MIT",
"main": "dist/index.js",

11
packages/data/src/checkParameter.ts
View File

@@ -1,8 +1,11 @@
/**
* Check if the parameter type is correct.
* @param value Parameter value.
* @param name Parameter name.
* @param type Expected parameter type.
* Validates the type of a given parameter against an expected type.
* Throws a {@link TypeError} if the validation fails.
* This function is useful for ensuring that function arguments conform to expected types at runtime.
* @param value The value of the parameter to check.
* @param name The name of the parameter, used in the error message for easier debugging.
* @param type The expected JavaScript type as a string (e.g., 'string', 'number', 'object').
* @throws {TypeError} Throws an error if the type of `value` does not match the `type`.
*/
export default function checkParameter(value: any, name: string, type: string) {
if (typeof value !== type) {

60
packages/data/src/ethers.ts
View File

@@ -21,15 +21,23 @@ import getEvents from "./getEvents"
import SemaphoreABI from "./semaphoreABI.json"
import { EthersNetwork, EthersOptions, GroupResponse } from "./types"
/**
* The SemaphoreEthers class provides a high-level interface to interact with the Semaphore smart contract
* using the {@link https://docs.ethers.org/v5/ | ethers.js} library. It encapsulates all necessary functionalities to connect to Ethereum networks,
* manage contract instances, and perform operations such as retrieving group information or checking group memberships.
* This class simplifies the interaction with the Ethereum blockchain by abstracting the details of network connections
* and contract interactions.
*/
export default class SemaphoreEthers {
private _network: EthersNetwork | string
private _options: EthersOptions
private _contract: Contract
/**
* Initializes the Ethers object with an Ethereum network or custom URL.
* @param networkOrEthereumURL Ethereum network or custom URL.
* @param options Ethers options.
* Constructs a new SemaphoreEthers instance, initializing it with a network or a custom Ethereum node URL,
* and optional configuration settings for the ethers provider and contract.
* @param networkOrEthereumURL The Ethereum network name or a custom JSON-RPC URL to connect to.
* @param options Configuration options for the ethers provider and the Semaphore contract.
*/
constructor(networkOrEthereumURL: EthersNetwork | string = defaultNetwork, options: EthersOptions = {}) {
checkParameter(networkOrEthereumURL, "networkOrSubgraphURL", "string")
@@ -92,32 +100,32 @@ export default class SemaphoreEthers {
}
/**
* Returns the Ethereum network or custom URL.
* @returns Ethereum network or custom URL.
* Retrieves the Ethereum network or custom URL currently used by this instance.
* @returns The network or URL as a string.
*/
get network(): EthersNetwork | string {
return this._network
}
/**
* Returns the Ethers options.
* @returns Ethers options.
* Retrieves the options used for configuring the ethers provider and the Semaphore contract.
* @returns The configuration options.
*/
get options(): EthersOptions {
return this._options
}
/**
* Returns the contract object.
* @returns Contract object.
* Retrieves the ethers Contract instance used to interact with the Semaphore contract.
* @returns The Contract instance.
*/
get contract(): Contract {
return this._contract
}
/**
* Returns the list of group ids.
* @returns List of group ids.
* Fetches the list of group IDs from the Semaphore contract by querying the "GroupCreated" events.
* @returns A promise that resolves to an array of group IDs as strings.
*/
async getGroupIds(): Promise<string[]> {
const groups = await getEvents(this._contract, "GroupCreated", [], this._options.startBlock)
@@ -126,9 +134,10 @@ export default class SemaphoreEthers {
}
/**
* Returns a specific group.
* @param groupId Group id.
* @returns Specific group.
* Retrieves detailed information about a specific group by its ID. This method queries the Semaphore contract
* to get the group's admin, Merkle tree root, depth, and size.
* @param groupId The unique identifier of the group.
* @returns A promise that resolves to a GroupResponse object.
*/
async getGroup(groupId: string): Promise<GroupResponse> {
checkParameter(groupId, "groupId", "string")
@@ -157,9 +166,10 @@ export default class SemaphoreEthers {
}
/**
* Returns a list of group members.
* @param groupId Group id.
* @returns Group members.
* Fetches a list of members from a specific group. This method queries the Semaphore contract for events
* related to member additions and updates, and constructs the list of current group members.
* @param groupId The unique identifier of the group.
* @returns A promise that resolves to an array of member identity commitments as strings.
*/
async getGroupMembers(groupId: string): Promise<string[]> {
checkParameter(groupId, "groupId", "string")
@@ -241,9 +251,10 @@ export default class SemaphoreEthers {
}
/**
* Returns a list of group validated proofs.
* @param groupId Group id.
* @returns Group validated proofs.
* Retrieves a list of validated proofs for a specific group. This method queries the Semaphore contract
* for "ProofValidated" events and returns details about each proof.
* @param groupId The unique identifier of the group.
* @returns A promise that resolves to an array of validated proofs.
*/
async getGroupValidatedProofs(groupId: string): Promise<any> {
checkParameter(groupId, "groupId", "string")
@@ -272,10 +283,11 @@ export default class SemaphoreEthers {
}
/**
* Returns true if a member is part of group, and false otherwise.
* @param groupId Group id
* @param member Group member.
* @returns True if the member is part of the group, false otherwise.
* Checks whether a specific member is part of a group. This method queries the Semaphore contract
* to determine if the provided identity commitment is a member of the specified group.
* @param groupId The unique identifier of the group.
* @param member The identity commitment of the member to check.
* @returns A promise that resolves to true if the member is part of the group, otherwise false.
*/
async isGroupMember(groupId: string, member: string): Promise<boolean> {
checkParameter(groupId, "groupId", "string")

12
packages/data/src/getEvents.ts
View File

@@ -2,12 +2,12 @@
import { Contract, EventLog } from "ethers/contract"
/**
* Returns the list of events of a contract with possible filters.
* @param contract Contract instance.
* @param eventName Name of the event.
* @param filterArgs Filter arguments.
* @param startBlock Block from which to start fetching.
* @returns List of contract events.
* Fetches a list of blockchain events from a smart contract based on specified filters and starting block.
* @param contract An instance of an ethers Contract connected to the blockchain.
* @param eventName The name of the event to filter.
* @param filterArgs Optional arguments to further filter the events.
* @param startBlock The block number from which to start fetching events (defaults to 0).
* @returns A promise that resolves to an array of event logs, each including event arguments and the block number.
*/
export default async function getEvents(
contract: Contract,

1
packages/data/src/getURL.ts
View File

@@ -3,6 +3,7 @@ import { isSupportedNetwork } from "@semaphore-protocol/utils/networks"
/**
* Returns the subgraph URL related to the network passed as a parameter.
* This function retrieves the URL of the Semaphore subgraph based on the provided network.
* @param supportedNetwork Semaphore supported network.
* @returns Subgraph URL.
*/

8
packages/data/src/request.ts
View File

@@ -1,10 +1,10 @@
import axios, { AxiosRequestConfig, AxiosResponse } from "axios"
/**
* Returns the response data of an HTTP request.
* @param url HTTP URL.
* @param config Axios request configuration.
* @returns Request data.
* Sends an HTTP request to a specified URL and returns the parsed response data.
* @param url The URL to which the HTTP request is sent.
* @param config Optional Axios request configuration to customize headers, method, timeout, etc.
* @returns A promise that resolves to the data extracted from the response, typically in JSON format.
*/
/* istanbul ignore next */
export default async function request(url: string, config?: AxiosRequestConfig): Promise<any> {

62
packages/data/src/subgraph.ts
View File

@@ -6,12 +6,22 @@ import request from "./request"
import { GroupOptions, GroupResponse } from "./types"
import { jsDateToGraphqlDate } from "./utils"
/**
* The SemaphoreSubgraph class provides an interface to interact with the Semaphore smart contract
* via subgraph queries. It enables operations such as retrieving lists of group members and validated proofs,
* as well as checking membership within groups.
* Each group in Semaphore is represented as a {@link https://zkkit.pse.dev/classes/_zk_kit_imt.LeanIMT.html | LeanIMT}
* (Lean Incremental Merkle Tree). This class supports interaction through either a
* {@link SupportedNetwork} or a direct URL to the subgraph. The subgraphs themselves are hosted on
* {@link https://thegraph.com/ | The Graph} protocol, facilitating efficient and decentralized query processing.
*/
export default class SemaphoreSubgraph {
private _url: string
/**
* Initializes the subgraph object with one of the supported networks or a custom URL.
* @param networkOrSubgraphURL Supported Semaphore network or custom Subgraph URL.
* Initializes the SemaphoreSubgraph instance with a supported network or a custom subgraph URL.
* This allows to interact with the Semaphore smart contract through the specified endpoint.
* @param networkOrSubgraphURL Either a supported network identifier or a direct URL to the subgraph.
*/
constructor(networkOrSubgraphURL: SupportedNetwork | string = defaultNetwork) {
checkParameter(networkOrSubgraphURL, "networkOrSubgraphURL", "string")
@@ -25,16 +35,18 @@ export default class SemaphoreSubgraph {
}
/**
* Returns the subgraph URL.
* @returns Subgraph URL.
* Retrieves the URL of the subgraph currently being used by the instance.
* This URL points to the specific subgraph where Semaphore data is stored.
* @returns The URL of the subgraph.
*/
get url(): string {
return this._url
}
/**
* Returns the list of group ids.
* @returns List of group ids.
* Fetches a list of all group IDs from the subgraph. This method queries the subgraph to retrieve
* identifiers for all groups managed by the Semaphore smart contract.
* @returns A promise that resolves to an array of group IDs.
*/
async getGroupIds(): Promise<string[]> {
const config: AxiosRequestConfig = {
@@ -54,9 +66,11 @@ export default class SemaphoreSubgraph {
}
/**
* Returns the list of groups.
* @param options Options to select the group parameters.
* @returns List of groups.
* Retrieves detailed information about groups from the subgraph based on the provided options.
* This method can filter groups by various parameters and include additional details like members
* and validated proofs if specified in the options.
* @param options Configuration options to filter groups and specify which additional details to fetch.
* @returns A promise that resolves to an array of group details.
*/
async getGroups(options: GroupOptions = {}): Promise<GroupResponse[]> {
checkParameter(options, "options", "object")
@@ -143,10 +157,11 @@ export default class SemaphoreSubgraph {
}
/**
* Returns a specific group.
* @param groupId Group id.
* @param options Options to select the group parameters.
* @returns Specific group.
* Fetches detailed information about a specific group by its ID. This method can also retrieve
* members and validated proofs for the group if requested via options.
* @param groupId The unique identifier of the group.
* @param options Configuration options to specify which details to fetch about the group.
* @returns A promise that resolves to the details of the specified group.
*/
async getGroup(groupId: string, options: Omit<GroupOptions, "filters"> = {}): Promise<GroupResponse> {
checkParameter(groupId, "groupId", "string")
@@ -204,9 +219,9 @@ export default class SemaphoreSubgraph {
}
/**
* Returns a list of group members.
* @param groupId Group id.
* @returns Group members.
* Retrieves a list of members from a specific group.
* @param groupId The unique identifier of the group.
* @returns A promise that resolves to an array of group members' identity commitments.
*/
async getGroupMembers(groupId: string): Promise<string[]> {
const group = await this.getGroup(groupId, { members: true }) // parameters are checked inside getGroup
@@ -214,9 +229,9 @@ export default class SemaphoreSubgraph {
}
/**
* Returns a list of validated proofs.
* @param groupId Group id.
* @returns Validated proofs.
* Fetches a list of validated proofs for a specific group.
* @param groupId The unique identifier of the group.
* @returns A promise that resolves to an array of validated proofs.
*/
async getGroupValidatedProofs(groupId: string): Promise<any[]> {
const group = await this.getGroup(groupId, { validatedProofs: true }) // parameters are checked inside getGroup
@@ -225,10 +240,11 @@ export default class SemaphoreSubgraph {
}
/**
* Returns true if a member is part of group, and false otherwise.
* @param groupId Group id
* @param member Group member.
* @returns True if the member is part of the group, false otherwise.
* Determines whether a specific member is part of a group. This method queries the subgraph to check
* if the provided member's identity commitment exists within the specified group.
* @param groupId The unique identifier of the group.
* @param member The identity commitment of the member to check.
* @returns A promise that resolves to true if the member is part of the group, otherwise false.
*/
async isGroupMember(groupId: string, member: string): Promise<boolean> {
checkParameter(groupId, "groupId", "string")

5
packages/data/src/utils.ts
View File

@@ -1,3 +1,8 @@
/**
* Converts a JavaScript Date object into a Unix timestamp.
* @param date The Date object to convert.
* @returns The Unix timestamp equivalent of the provided Date object.
*/
// eslint-disable-next-line import/prefer-default-export
export function jsDateToGraphqlDate(date: Date): number {
return Math.round(date.getTime() / 1000)