Skip to content

Commit 4089b81

Browse files
JuArceJuArce
committed
docs: add docs for lock, unlock and withdraw funds
1 parent f414cac commit 4089b81

File tree

2 files changed

+242
-0
lines changed

2 files changed

+242
-0
lines changed

‎docs/3_guides/1.2_SDK_api_reference.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -432,6 +432,126 @@ pub async fn get_balance_in_aligned(
432432
- `EthereumProviderError` if there is an error in the connection with the RPC provider.
433433
- `EthereumCallError` if there is an error in the Ethereum call.
434434

435+
### `lock_balance_in_aligned`
436+
437+
Locks the balance of a user in the Aligned payment service.
438+
439+
```rust
440+
pub async fn lock_balance_in_aligned(
441+
signer: &SignerMiddleware<Provider<Http>, LocalWallet>,
442+
network: Network,
443+
) -> Result<ethers::types::TransactionReceipt, errors::PaymentError>
444+
```
445+
446+
#### Arguments
447+
448+
- `signer` - The signer middleware containing the user's wallet and provider.
449+
- `network` - The network on which the lock operation will be performed.
450+
451+
#### Returns
452+
453+
- `Result<ethers::types::TransactionReceipt, errors::PaymentError>` - The transaction receipt of the lock operation.
454+
455+
#### Description
456+
457+
This function locks the user's balance, preventing it from being withdrawn. Locked balances can be used for proof verification payments but cannot be withdrawn until they are unlocked using `unlock_balance_in_aligned` and the lock period expires.
458+
459+
#### Errors
460+
461+
- `SendError` if there is an error sending the transaction.
462+
- `SubmitError` if there is an error submitting the transaction.
463+
464+
### `unlock_balance_in_aligned`
465+
466+
Unlocks the balance of a user in the Aligned payment service.
467+
468+
```rust
469+
pub async fn unlock_balance_in_aligned(
470+
signer: &SignerMiddleware<Provider<Http>, LocalWallet>,
471+
network: Network,
472+
) -> Result<ethers::types::TransactionReceipt, errors::PaymentError>
473+
```
474+
475+
#### Arguments
476+
477+
- `signer` - The signer middleware containing the user's wallet and provider.
478+
- `network` - The network on which the unlock operation will be performed.
479+
480+
#### Returns
481+
482+
- `Result<ethers::types::TransactionReceipt, errors::PaymentError>` - The transaction receipt of the unlock operation.
483+
484+
#### Description
485+
486+
This function initiates an unlock request for the user's balance. After calling this function, the user's balance will be locked for a certain period before it can be withdrawn. Use `get_unlock_block_time` to check when the balance can be withdrawn.
487+
488+
#### Errors
489+
490+
- `SendError` if there is an error sending the transaction.
491+
- `SubmitError` if there is an error submitting the transaction.
492+
493+
### `get_unlock_block_time`
494+
495+
Returns the timestamp when a user's balance will be unlocked and available for withdrawal.
496+
497+
```rust
498+
pub async fn get_unlock_block_time(
499+
user: Address,
500+
eth_rpc_url: &str,
501+
network: Network,
502+
) -> Result<u64, errors::BalanceError>
503+
```
504+
505+
#### Arguments
506+
507+
- `user` - The address of the user to check the unlock time for.
508+
- `eth_rpc_url` - The URL of the Ethereum RPC node.
509+
- `network` - The network on which to check the unlock time.
510+
511+
#### Returns
512+
513+
- `Result<u64, errors::BalanceError>` - The timestamp when the user's balance will be unlocked (as u64).
514+
515+
#### Description
516+
517+
After calling `unlock_balance_in_aligned`, users must wait for the lock period before they can withdraw their funds using `withdraw_balance_from_aligned`.
518+
519+
#### Errors
520+
521+
- `EthereumProviderError` if there is an error in the connection with the RPC provider.
522+
- `EthereumCallError` if there is an error in the Ethereum call.
523+
524+
### `withdraw_balance_from_aligned`
525+
526+
Withdraws a specified amount from the user's balance in the Aligned payment service.
527+
528+
```rust
529+
pub async fn withdraw_balance_from_aligned(
530+
signer: &SignerMiddleware<Provider<Http>, LocalWallet>,
531+
network: Network,
532+
amount: U256,
533+
) -> Result<ethers::types::TransactionReceipt, errors::PaymentError>
534+
```
535+
536+
#### Arguments
537+
538+
- `signer` - The signer middleware containing the user's wallet and provider.
539+
- `network` - The network on which the withdrawal will be performed.
540+
- `amount` - The amount to withdraw from the user's balance.
541+
542+
#### Returns
543+
544+
- `Result<ethers::types::TransactionReceipt, errors::PaymentError>` - The transaction receipt of the withdrawal operation.
545+
546+
#### Description
547+
548+
This function can only be called after the balance has been unlocked using `unlock_balance_in_aligned` and the lock period has expired. Use `get_unlock_block_time` to check when the withdrawal becomes available.
549+
550+
#### Errors
551+
552+
- `SendError` if there is an error sending the transaction.
553+
- `SubmitError` if there is an error submitting the transaction.
554+
435555
### `get_vk_commitment`
436556

437557
Returns the commitment for the verification key, taking into account the corresponding proving system.

‎docs/3_guides/9_aligned_cli.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -357,6 +357,128 @@ aligned get-user-amount-of-queued-proofs \
357357
```
358358

359359

360+
---
361+
362+
### **lock-funds**
363+
364+
#### Description:
365+
366+
Locks funds in the batcher. Locked balances can be used for proof verification payments but cannot be withdrawn until they are unlocked and the lock period expires.
367+
368+
#### Command:
369+
370+
`lock-funds [OPTIONS]`
371+
372+
#### Options:
373+
374+
- `--keystore_path <path_to_local_keystore>`: Path to the local keystore.
375+
- `--private_key <private_key>`: User's wallet private key.
376+
- `--rpc_url <RPC_provider_url>`: User's Ethereum RPC provider connection address.
377+
- Default: `http://localhost:8545`
378+
- Mainnet: `https://ethereum-rpc.publicnode.com`
379+
- Holesky: `https://ethereum-holesky-rpc.publicnode.com`
380+
- Hoodi: `https://ethereum-hoodi-rpc.publicnode.com`
381+
- Also, you can use your own Ethereum RPC providers.
382+
- One of the following, to specify which Network to interact with:
383+
- `--network <working_network_name>`: Network name to interact with.
384+
- Default: `devnet`
385+
- Possible values: `devnet`, `holesky`, `mainnet`, `hoodi`
386+
- For a custom Network, you must specify the following parameters:
387+
- `--aligned_service_manager <aligned_service_manager_contract_address>`
388+
- `--batcher_payment_service <batcher_payment_service_contract_address>`
389+
- `--batcher_url <batcher_websocket_url>`
390+
391+
#### Example:
392+
393+
```bash
394+
aligned lock-funds \
395+
--network holesky \
396+
--rpc_url https://ethereum-holesky-rpc.publicnode.com \
397+
--keystore_path <KEYSTORE_PATH>
398+
```
399+
400+
---
401+
402+
### **unlock-funds**
403+
404+
#### Description:
405+
406+
Unlocks funds from the batcher. After calling this command, users must wait for the lock period before they can withdraw their funds using `withdraw-funds`.
407+
408+
#### Command:
409+
410+
`unlock-funds [OPTIONS]`
411+
412+
#### Options:
413+
414+
- `--keystore_path <path_to_local_keystore>`: Path to the local keystore.
415+
- `--private_key <private_key>`: User's wallet private key.
416+
- `--rpc_url <RPC_provider_url>`: User's Ethereum RPC provider connection address.
417+
- Default: `http://localhost:8545`
418+
- Mainnet: `https://ethereum-rpc.publicnode.com`
419+
- Holesky: `https://ethereum-holesky-rpc.publicnode.com`
420+
- Hoodi: `https://ethereum-hoodi-rpc.publicnode.com`
421+
- Also, you can use your own Ethereum RPC providers.
422+
- One of the following, to specify which Network to interact with:
423+
- `--network <working_network_name>`: Network name to interact with.
424+
- Default: `devnet`
425+
- Possible values: `devnet`, `holesky`, `mainnet`, `hoodi`
426+
- For a custom Network, you must specify the following parameters:
427+
- `--aligned_service_manager <aligned_service_manager_contract_address>`
428+
- `--batcher_payment_service <batcher_payment_service_contract_address>`
429+
- `--batcher_url <batcher_websocket_url>`
430+
431+
#### Example:
432+
433+
```bash
434+
aligned unlock-funds \
435+
--network holesky \
436+
--rpc_url https://ethereum-holesky-rpc.publicnode.com \
437+
--keystore_path <KEYSTORE_PATH>
438+
```
439+
440+
---
441+
442+
### **withdraw-funds**
443+
444+
#### Description:
445+
446+
Withdraws a specified amount from the user's balance in the batcher. This command can only be used after the balance has been unlocked using `unlock-funds` and the lock period has expired.
447+
448+
#### Command:
449+
450+
`withdraw-funds [OPTIONS] --amount <amount_to_withdraw>`
451+
452+
#### Options:
453+
454+
- `--keystore_path <path_to_local_keystore>`: Path to the local keystore.
455+
- `--private_key <private_key>`: User's wallet private key.
456+
- `--rpc_url <RPC_provider_url>`: User's Ethereum RPC provider connection address.
457+
- Default: `http://localhost:8545`
458+
- Mainnet: `https://ethereum-rpc.publicnode.com`
459+
- Holesky: `https://ethereum-holesky-rpc.publicnode.com`
460+
- Hoodi: `https://ethereum-hoodi-rpc.publicnode.com`
461+
- Also, you can use your own Ethereum RPC providers.
462+
- `--amount <amount (ether)>`: Amount of Ether to withdraw.
463+
- One of the following, to specify which Network to interact with:
464+
- `--network <working_network_name>`: Network name to interact with.
465+
- Default: `devnet`
466+
- Possible values: `devnet`, `holesky`, `mainnet`, `hoodi`
467+
- For a custom Network, you must specify the following parameters:
468+
- `--aligned_service_manager <aligned_service_manager_contract_address>`
469+
- `--batcher_payment_service <batcher_payment_service_contract_address>`
470+
- `--batcher_url <batcher_websocket_url>`
471+
472+
#### Example:
473+
474+
```bash
475+
aligned withdraw-funds \
476+
--network holesky \
477+
--rpc_url https://ethereum-holesky-rpc.publicnode.com \
478+
--amount 0.5ether \
479+
--keystore_path <KEYSTORE_PATH>
480+
```
481+
360482
---
361483
362484
### **verify-agg-proof**

0 commit comments

Comments
 (0)