Skip to content

[SDK][Python] Align python sdk implementation with ts #3380

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
portuu3 merged 3 commits into from
Jun 18, 2025
Merged

[SDK][Python] Align python sdk implementation with ts #3380

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
21be9f6
Refactor Python SDK to use same structure as Typescript one
flopez7 Jun 4, 2025
ac174ae
Refactor SDK documentation and examples
flopez7 Jun 16, 2025
c1db0d0
Merge branch 'develop' into feat/sdk/python-refactor
flopez7 Jun 16, 2025
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
433 changes: 9 additions & 424 deletions docs/sdk/python/human_protocol_sdk.escrow.escrow_client.md
View file
Open in desktop

Large diffs are not rendered by default.

118 changes: 3 additions & 115 deletions docs/sdk/python/human_protocol_sdk.kvstore.kvstore_client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,123 +63,11 @@ Initializes a KVStore instance.
* **web3** (`Web3`) – The Web3 object
* **gas_limit** (`Optional`[`int`]) – (Optional) Gas limit for transactions

#### set(key, value, tx_options=None)
#### set(\*args, \*\*kwargs)

Sets the value of a key-value pair in the contract.
#### set_bulk(\*args, \*\*kwargs)

* **Parameters:**
* **key** (`str`) – The key of the key-value pair to set
* **value** (`str`) – The value of the key-value pair to set
* **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
* **Return type:**
`None`
* **Returns:**
None
* **Example:**
```python
from eth_typing import URI
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from web3.providers.auto import load_provider_from_uri

from human_protocol_sdk.kvstore import KVStoreClient

def get_w3_with_priv_key(priv_key: str):
w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
gas_payer = w3.eth.account.from_key(priv_key)
w3.eth.default_account = gas_payer.address
w3.middleware_onion.inject(
SignAndSendRawMiddlewareBuilder.build(priv_key),
'SignAndSendRawMiddlewareBuilder',
layer=0,
)
return (w3, gas_payer)

(w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
kvstore_client = KVStoreClient(w3)
kvstore_client.set('Role', 'RecordingOracle')
```

#### set_bulk(keys, values, tx_options=None)

Sets multiple key-value pairs in the contract.

* **Parameters:**
* **keys** (`List`[`str`]) – A list of keys to set
* **values** (`List`[`str`]) – A list of values to set
* **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
* **Return type:**
`None`
* **Returns:**
None
* **Example:**
```python
from eth_typing import URI
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from web3.providers.auto import load_provider_from_uri

from human_protocol_sdk.kvstore import KVStoreClient

def get_w3_with_priv_key(priv_key: str):
w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
gas_payer = w3.eth.account.from_key(priv_key)
w3.eth.default_account = gas_payer.address
w3.middleware_onion.inject(
SignAndSendRawMiddlewareBuilder.build(priv_key),
'SignAndSendRawMiddlewareBuilder',
layer=0,
)
return (w3, gas_payer)

(w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
kvstore_client = KVStoreClient(w3)

keys = ['Role', 'Webhook_url']
values = ['RecordingOracle', 'http://localhost']
kvstore_client.set_bulk(keys, values)
```

#### set_file_url_and_hash(url, key='url', tx_options=None)

Sets a URL value for the address that submits the transaction, and its hash.

* **Parameters:**
* **url** (`str`) – URL to set
* **key** (`Optional`[`str`]) – Configurable URL key. url by default.
* **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
* **Return type:**
`None`
* **Returns:**
None
* **Raises:**
[**KVStoreClientError**](#human_protocol_sdk.kvstore.kvstore_client.KVStoreClientError) – If an error occurs while validating URL, or handling transaction
* **Example:**
```python
from eth_typing import URI
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from web3.providers.auto import load_provider_from_uri

from human_protocol_sdk.kvstore import KVStoreClient

def get_w3_with_priv_key(priv_key: str):
w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
gas_payer = w3.eth.account.from_key(priv_key)
w3.eth.default_account = gas_payer.address
w3.middleware_onion.inject(
SignAndSendRawMiddlewareBuilder.build(priv_key),
'SignAndSendRawMiddlewareBuilder',
layer=0,
)
return (w3, gas_payer)

(w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
kvstore_client = KVStoreClient(w3)

kvstore_client.set_file_url_and_hash('http://localhost')
kvstore_client.set_file_url_and_hash('https://linkedin.com/me', 'linkedin_url')
```
#### set_file_url_and_hash(\*args, \*\*kwargs)

### *exception* human_protocol_sdk.kvstore.kvstore_client.KVStoreClientError

Expand Down
2 changes: 1 addition & 1 deletion docs/sdk/python/human_protocol_sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,7 @@
* [`get_hmt_balance()`](human_protocol_sdk.utils.md#human_protocol_sdk.utils.get_hmt_balance)
* [`get_kvstore_interface()`](human_protocol_sdk.utils.md#human_protocol_sdk.utils.get_kvstore_interface)
* [`get_staking_interface()`](human_protocol_sdk.utils.md#human_protocol_sdk.utils.get_staking_interface)
* [`handle_transaction()`](human_protocol_sdk.utils.md#human_protocol_sdk.utils.handle_transaction)
* [`handle_error()`](human_protocol_sdk.utils.md#human_protocol_sdk.utils.handle_error)
* [`parse_transfer_transaction()`](human_protocol_sdk.utils.md#human_protocol_sdk.utils.parse_transfer_transaction)
* [`validate_url()`](human_protocol_sdk.utils.md#human_protocol_sdk.utils.validate_url)
* [`with_retry()`](human_protocol_sdk.utils.md#human_protocol_sdk.utils.with_retry)
212 changes: 5 additions & 207 deletions docs/sdk/python/human_protocol_sdk.staking.staking_client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,45 +62,7 @@ Initializes a Staking instance
* **Parameters:**
**w3** (`Web3`) – Web3 instance

#### approve_stake(amount, tx_options=None)

Approves HMT token for Staking.

* **Parameters:**
* **amount** (`Decimal`) – Amount to approve
* **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
* **Return type:**
`None`
* **Returns:**
None
* **Validate:**
Amount must be greater than 0
* **Example:**
```python
from eth_typing import URI
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from web3.providers.auto import load_provider_from_uri

from human_protocol_sdk.staking import StakingClient

def get_w3_with_priv_key(priv_key: str):
w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
gas_payer = w3.eth.account.from_key(priv_key)
w3.eth.default_account = gas_payer.address
w3.middleware_onion.inject(
SignAndSendRawMiddlewareBuilder.build(priv_key),
'SignAndSendRawMiddlewareBuilder',
layer=0,
)
return (w3, gas_payer)

(w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
staking_client = StakingClient(w3)

amount = Web3.to_wei(5, 'ether') # convert from ETH to WEI
staking_client.approve_stake(amount)
```
#### approve_stake(\*args, \*\*kwargs)

#### get_staker_info(staker_address)

Expand Down Expand Up @@ -129,177 +91,13 @@ Retrieves comprehensive staking information for a staker.
print(staking_info['stakedAmount'])
```

#### slash(slasher, staker, escrow_address, amount, tx_options=None)
#### slash(\*args, \*\*kwargs)

Slashes HMT token.
#### stake(\*args, \*\*kwargs)

* **Parameters:**
* **slasher** (`str`) – Address of the slasher
* **staker** (`str`) – Address of the staker
* **escrow_address** (`str`) – Address of the escrow
* **amount** (`Decimal`) – Amount to slash
* **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
* **Return type:**
`None`
* **Returns:**
None
* **Validate:**
- Amount must be greater than 0
- Amount must be less than or equal to the amount allocated to the escrow (on-chain)
- Escrow address must be valid
* **Example:**
```python
from eth_typing import URI
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from web3.providers.auto import load_provider_from_uri

from human_protocol_sdk.staking import StakingClient

def get_w3_with_priv_key(priv_key: str):
w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
gas_payer = w3.eth.account.from_key(priv_key)
w3.eth.default_account = gas_payer.address
w3.middleware_onion.inject(
SignAndSendRawMiddlewareBuilder.build(priv_key),
'SignAndSendRawMiddlewareBuilder',
layer=0,
)
return (w3, gas_payer)

(w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
staking_client = StakingClient(w3)

amount = Web3.to_wei(5, 'ether') # convert from ETH to WEI
staking_client.slash(
'0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
'0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
'0x62dD51230A30401C455c8398d06F85e4EaB6309f',
amount
)
```

#### stake(amount, tx_options=None)
#### unstake(\*args, \*\*kwargs)

Stakes HMT token.

* **Parameters:**
* **amount** (`Decimal`) – Amount to stake
* **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
* **Return type:**
`None`
* **Returns:**
None
* **Validate:**
- Amount must be greater than 0
- Amount must be less than or equal to the approved amount (on-chain)
- Amount must be less than or equal to the balance of the staker (on-chain)
* **Example:**
```python
from eth_typing import URI
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from web3.providers.auto import load_provider_from_uri

from human_protocol_sdk.staking import StakingClient

def get_w3_with_priv_key(priv_key: str):
w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
gas_payer = w3.eth.account.from_key(priv_key)
w3.eth.default_account = gas_payer.address
w3.middleware_onion.inject(
SignAndSendRawMiddlewareBuilder.build(priv_key),
'SignAndSendRawMiddlewareBuilder',
layer=0,
)
return (w3, gas_payer)

(w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
staking_client = StakingClient(w3)

amount = Web3.to_wei(5, 'ether') # convert from ETH to WEI
staking_client.approve_stake(amount) # if it was already approved before, this is not necessary
staking_client.stake(amount)
```

#### unstake(amount, tx_options=None)

Unstakes HMT token.

* **Parameters:**
* **amount** (`Decimal`) – Amount to unstake
* **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
* **Return type:**
`None`
* **Returns:**
None
* **Validate:**
- Amount must be greater than 0
- Amount must be less than or equal to the staked amount which is not locked / allocated (on-chain)
* **Example:**
```python
from eth_typing import URI
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from web3.providers.auto import load_provider_from_uri

from human_protocol_sdk.staking import StakingClient

def get_w3_with_priv_key(priv_key: str):
w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
gas_payer = w3.eth.account.from_key(priv_key)
w3.eth.default_account = gas_payer.address
w3.middleware_onion.inject(
SignAndSendRawMiddlewareBuilder.build(priv_key),
'SignAndSendRawMiddlewareBuilder',
layer=0,
)
return (w3, gas_payer)

(w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
staking_client = StakingClient(w3)

amount = Web3.to_wei(5, 'ether') # convert from ETH to WEI
staking_client.unstake(amount)
```

#### withdraw(tx_options=None)

Withdraws HMT token.

* **Parameters:**
**tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
* **Return type:**
`None`
* **Returns:**
None
* **Validate:**
- There must be unstaked tokens which is unlocked (on-chain)
* **Example:**
```python
from eth_typing import URI
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from web3.providers.auto import load_provider_from_uri

from human_protocol_sdk.staking import StakingClient

def get_w3_with_priv_key(priv_key: str):
w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
gas_payer = w3.eth.account.from_key(priv_key)
w3.eth.default_account = gas_payer.address
w3.middleware_onion.inject(
SignAndSendRawMiddlewareBuilder.build(priv_key),
'SignAndSendRawMiddlewareBuilder',
layer=0,
)
return (w3, gas_payer)

(w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
staking_client = StakingClient(w3)

staking_client.withdraw()
```
#### withdraw(\*args, \*\*kwargs)

### *exception* human_protocol_sdk.staking.staking_client.StakingClientError

Expand Down
Loading
Loading