Skip to content

docs: bump docs on payment service and SDK #1168

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
entropidelic merged 5 commits into from
Oct 14, 2024
Merged

docs: bump docs on payment service and SDK #1168

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b6799e8
refactor(docs): send funds to aligned using CLI
uri-99 Oct 3, 2024
212c77d
docs: SDK adding of new funcs
uri-99 Oct 3, 2024
18a2fd5
Merge branch 'staging' into 1112-add-docs-on-how-the-payment-system-w…
uri-99 Oct 7, 2024
da19601
fix: typos on arquitecture payment service
uri-99 Oct 8, 2024
cfdb719
Merge branch 'staging' into 1112-add-docs-on-how-the-payment-system-w…
uri-99 Oct 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/2_architecture/components/2_payment_service_contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
The Payment Service handles users payments to fund the verification of their proofs.

To be able to use the batcher, a user must fund its transactions.
For this, there is a simple Batcher Payment System.
For this, there is a simple Payment Service.

The Batcher has an associated Batcher Payments smart contract,
The Batcher has an associated `Batcher Payments` smart contract,
which is in charge of receiving user's payments,
and it guarantees that it can only spend these funds to send users' proofs to Aligned.

Expand Down
34 changes: 16 additions & 18 deletions docs/3_guides/0_submitting_proofs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,33 +60,32 @@ This will create the ECDSA keystore file in `~/.aligned_keystore/keystore0`

- If you have the EigenLayer CLI installed, the keystore can be generated following [these](https://docs.eigenlayer.xyz/eigenlayer/operator-guides/operator-installation#import-keys) instructions. The key will be stored into `~/.eigenlayer/operator_keys`.

## 2. Fund the batcher
## 2. Send funds to Aligned

To be able to send proofs to Aligned using the Batcher, the user must fund its transactions. For this, there is a simple Batcher Payment System.
To send proofs to Aligned using the Batcher, the user must first deposit some funds in Aligned to pay for the verification of his proofs.
Copy link
Copy Markdown
Contributor

@PatStiles PatStiles Oct 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I recommend we are explicit try to be specific about what part of Aligned we are interacting with something like the user must first deposit some funds in Aligned to pay -> the user must first deposit funds into the Aligned BatcherPaymentService to pay for the verification. The Batcher verifies the user has available to pay for its proof before processing its proof contract payment contract.

Copy link
Copy Markdown
Contributor Author

@uri-99 uri-99 Oct 8, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The idea of this PR was actually to remove this because the user doesn't need this information here. This information is better explained in docs/2_architecture/components/2_payment_service_contract.md


To use it, you can use the `aligned` CLI, as shown with the following example:

```bash
aligned deposit-to-batcher \
aligned deposit-to-batcher \
--rpc_url https://ethereum-holesky-rpc.publicnode.com \
--network holesky \
--keystore_path <keystore_path> \
--amount 0.1ether
```

These commands allow the usage of the following flags:
This command allows the usage of the following flags:

- `--payment_service_addr` to specify the address of the Batcher Payment Service smart contract.
- `--rpc_url` to specify the rpc url to be used.
- `--network` to specify the chain id to be used. Could be holesky or devnet.
- `--network` to specify the netowrk to be used. Can be `devnet`, `holesky-stage` or `holesky`.
- `--keystore_path` the path to the keystore.
- `--amount` the number of ethers to transfer to the Batcher.
- Note: `--amount` flag parameter must be with the shown format. The amount followed by the `ether` keyword to specify how many ethers you wish to deposit to the Batcher.
- Note: `--amount` flag parameter must be with the shown format, `XX.XXether`.

After depositing funds, you can verify the Service has correctly received them by executing the following command:

```bash
aligned get-user-balance \
aligned get-user-balance \
--rpc_url https://ethereum-holesky-rpc.publicnode.com \
--network holesky \
--user_addr <user_addr>
Expand All @@ -95,7 +94,7 @@ aligned get-user-balance \
These commands allow the usage of the following flags:

- `--rpc_url` to specify the rpc url to be used.
- `--network` to specify the chain id to be used. Could be holesky or devnet.
- `--network` to specify the netowrk to be used. Can be `devnet`, `holesky-stage` or `holesky`.
- `--user_addr` the address of the user that funded the Batcher.

## 3. Submit your proof to the batcher
Expand All @@ -109,9 +108,8 @@ Proof submission is done via the `submit` command of the Aligned CLI. The argume
* `vm_program`: When the proving system involves the execution of a program in a zkVM, this argument is associated with the compiled program or some other identifier of the program.
* `pub_input`: The path to the file with the public input associated with the proof.
* `batcher_url`: The batcher websocket URL.
* `chain` to specify the chain id to be used. Could be holesky or devnet.
* `network` to specify the netowrk to be used. Can be `devnet`, `holesky-stage` or `holesky`.
* `rpc_url`: The RPC Ethereum node URL.
* `payment_service_addr`: The Ethereum address of the Batcher Payments System contract.
* `proof_generator_addr`: An optional parameter that can be used in some applications to avoid front-running.
* `batch_inclusion_data_directory_path`: An optional parameter indicating the directory where to store the batcher response data. If not provided, the folder with the responses will be created in the current directory.

Expand All @@ -132,7 +130,7 @@ aligned submit \
--batch_inclusion_data_directory_path [batch_inclusion_data_directory_path] \
--keystore_path <path_to_ecdsa_keystore> \
--network holesky \
--rpc_url https://ethereum-holesky-rpc.publicnode.com
--rpc_url https://ethereum-holesky-rpc.publicnode.com
```

**Example**
Expand All @@ -146,7 +144,7 @@ aligned submit \
--batcher_url wss://batcher.alignedlayer.com \
--keystore_path ~/.aligned_keystore/keystore0 \
--network holesky \
--rpc_url https://ethereum-holesky-rpc.publicnode.com
--rpc_url https://ethereum-holesky-rpc.publicnode.com
```

### Risc0 proof
Expand All @@ -167,7 +165,7 @@ aligned submit \
--batch_inclusion_data_directory_path [batch_inclusion_data_directory_path] \
--keystore_path <path_to_ecdsa_keystore> \
--network holesky \
--rpc_url https://ethereum-holesky-rpc.publicnode.com
--rpc_url https://ethereum-holesky-rpc.publicnode.com
```

**NOTE**: As said above, Aligned currently supports Risc0 proofs from `risc0-zkvm` version `v1.0.1`. For generating proofs using `cargo risc-zero` please ensure you are using `v1.0.1` or your proof will not be verified.
Expand All @@ -193,7 +191,7 @@ aligned submit \
--aligned_verification_data_path ~/.aligned/aligned_verification_data \
--keystore_path ~/.aligned_keystore/keystore0 \
--network holesky \
--rpc_url https://ethereum-holesky-rpc.publicnode.com
--rpc_url https://ethereum-holesky-rpc.publicnode.com
```

### GnarkPlonkBn254, GnarkPlonkBls12_381 and Groth16Bn254
Expand All @@ -212,7 +210,7 @@ aligned submit \
--batch_inclusion_data_directory_path [batch_inclusion_data_directory_path] \
--keystore_path <path_to_ecdsa_keystore> \
--network holesky \
--rpc_url https://ethereum-holesky-rpc.publicnode.com
--rpc_url https://ethereum-holesky-rpc.publicnode.com
```

**Examples**:
Expand All @@ -227,7 +225,7 @@ aligned submit \
--batcher_url wss://batcher.alignedlayer.com \
--keystore_path ~/.aligned_keystore/keystore0 \
--network holesky \
--rpc_url https://ethereum-holesky-rpc.publicnode.com
--rpc_url https://ethereum-holesky-rpc.publicnode.com
```

```bash
Expand All @@ -240,7 +238,7 @@ aligned submit \
--batcher_url wss://batcher.alignedlayer.com \
--keystore_path ~/.aligned_keystore/keystore0 \
--network holesky \
--rpc_url https://ethereum-holesky-rpc.publicnode.com
--rpc_url https://ethereum-holesky-rpc.publicnode.com
```

```bash
Expand Down
66 changes: 59 additions & 7 deletions docs/3_guides/1.2_SDK_api_reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,7 +290,7 @@ Should be used before submitting proofs to the batcher. Wallet chain id needs to
wallet = wallet.with_chain_id(chain_id);
```

### Arguments
#### Arguments

- `eth_rpc_url` - The URL of the Ethereum RPC node.

Expand All @@ -303,7 +303,7 @@ wallet = wallet.with_chain_id(chain_id);
- `EthereumProviderError` if there is an error in the connection with the RPC provider.
- `EthereumCallError` if there is an error in the Ethereum call.

## `estimate_fee`
### `estimate_fee`

Estimates the fee the user would have to pay for submitting a proof to Aligned. Depending on the
priority the user wants to have in the batch, the `estimate` parameter can be set.
Expand All @@ -315,7 +315,7 @@ pub async fn estimate_fee(
) -> Result<U256, errors::MaxFeeEstimateError>
```

### Arguments
#### Arguments

- `eth_rpc_url` - The URL of the Ethereum RPC node.
- `estimate` - The parameter to set the priority for the proof to be included in the batch. It can be one
Expand All @@ -330,7 +330,7 @@ pub async fn estimate_fee(
- `EthereumProviderError` if there is an error in the connection with the RPC provider.
- `EthereumCallError` if there is an error in the Ethereum call.

## `compute_max_fee`
### `compute_max_fee`

Computes `max_fee` for a proof based on the number of proofs in a batch (`num_proofs_per_batch`) and number of proofs (`num_proofs`) in that batch the user would pay for i.e (`num_proofs` / `num_proofs_per_batch`).

Expand All @@ -342,7 +342,7 @@ pub async fn compute_max_fee(
) -> Result<U256, errors::MaxFeeEstimateError>
```

### Arguments
#### Arguments

- `eth_rpc_url` - The URL of the Ethereum RPC node.
- `num_proofs` - The number of proofs in a batch the user would pay for.
Expand All @@ -357,7 +357,7 @@ pub async fn compute_max_fee(
- `EthereumProviderError` if there is an error in the connection with the RPC provider.
- `EthereumCallError` if there is an error in the Ethereum call.

## `fee_per_proof`
### `fee_per_proof`

Returns the `fee_per_proof` based on the current gas price for a batch compromised of `num_proofs_per_batch` i.e. (1 / `num_proofs_per_batch`).

Expand All @@ -368,7 +368,7 @@ pub async fn fee_per_proof(
) -> Result<U256, errors::MaxFeeEstimateError>
```

### Arguments
#### Arguments

- `eth_rpc_url` - The URL of the users Ethereum RPC node.
- `num_proofs_per_batch` - The number of proofs within a batch.
Expand All @@ -381,3 +381,55 @@ pub async fn fee_per_proof(

- `EthereumProviderError` if there is an error in the connection with the RPC provider.
- `EthereumCallError` if there is an error in the Ethereum call.


### `deposit_to_aligned`

Funds the batcher payment service in name of the signer

pub async fn deposit_to_aligned(
amount: U256,
signer: SignerMiddleware<Provider<Http>, LocalWallet>,
network: Network,
) -> Result<ethers::types::TransactionReceipt, errors::PaymentError> {

#### Arguments
`amount` - The amount to be paid.
`signer` - The signer middleware of the payer.
`network` - The network on which the payment will be done.

#### Returns
The receipt of the payment transaction.

#### Errors
`SendError` if there is an error sending the transaction.
`SubmitError` if there is an error submitting the transaction.
`PaymentFailed` if the payment failed.


### `get_balance_in_aligned`

Queries a User's balance that was deposited in Aligned

```rust
pub async fn get_balance_in_aligned(
user: Address,
eth_rpc_url: &str,
network: Network,
) -> Result<U256, errors::BalanceError> {
```

#### Arguments

`user` - The address of the user.
`eth_rpc_url` - The URL of the Ethereum RPC node.
`network` - The network on which the balance will be checked.

#### Returns

- `Result<U256, errors::BalanceError>` - The balance of the user in the payment service.

#### Errors

- `EthereumProviderError` if there is an error in the connection with the RPC provider.
- `EthereumCallError` if there is an error in the Ethereum call.