diff --git a/README.md b/README.md index a3dd405..a90cfba 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ +from snet.sdk import PaymentStrategyType # snet-sdk-python @@ -147,23 +148,53 @@ visit the [Payment](#payment) section. ## Payment -### Free call +When creating a service client, you can select a payment strategy using the `payment_strategy_type` parameter: -If you want to use the free calls you will need to pass this argument to the `create_service_client()` method: +```python +from snet.sdk import PaymentStrategyType -```python -address = "YOUR_ETHEREUM_ADDRESS" +payment_strategy_type = PaymentStrategyType. ``` +These are four payment strategies: + +- `PaymentStrategyType.DEFAULT` +- `PaymentStrategyType.FREE_CALL` +- `PaymentStrategyType.PAID_CALL` +- `PaymentStrategyType.PREPAID_CALL` + +The default payment strategy selects one of the other three each time the service is called, depending on the +availability of free calls, as well as the presence of parameters required for concurrent calls. While choosing +a specific payment strategy will not allow you to switch to another. This is especially convenient when you want +to use free calls without accidentally spending money. + +> Note: If you don't specify еру `payment_strategy_type` parameter, the default payment strategy will be used. + +### Free call + +If you want to use the free calls you will need to choose `PaymentStrategyType.FREE_CALL` as the payment strategy type. Creating a service client with free calls included would look like this: + ```python service_client = snet_sdk.create_service_client(org_id="26072b8b6a0e448180f8c0e702ab6d2f", service_id="Exampleservice", - address="0xtest") + payment_strategy_type = PaymentStrategyType.FREE_CALL) ``` ### Paid call +If you want to use regular paid calls you will need to choose `PaymentStrategyType.PAID_CALL` as the payment strategy type. +Creating a service client with paid calls would look like this: + +```python +service_client = snet_sdk.create_service_client(org_id="26072b8b6a0e448180f8c0e702ab6d2f", + service_id="Exampleservice", + payment_strategy_type = PaymentStrategyType.PAID_CALL) +``` + +There is no need to call functions for interacting with payment channels, because they are automatically +managed by the SDK. But anyway you can use them if you want. + #### Open channel with the specified amount of funds and expiration `open_channel()`[[1]](#1-this-method-uses-a-call-to-a-paid-smart-contract-function) opens a payment channel with the specified amount of AGIX tokens in cogs and expiration time. @@ -203,15 +234,20 @@ payment_channel.extend_and_add_funds(amount=123456, expiration=33333) ### Concurrent (Prepaid) call -Concurrent (prepaid) calls allow you to prepay for a batch of service calls in advance. This off-chain strategy is ideal for scenarios requiring high throughput and low latency. Unlike regular paid calls, the payment is done once upfront, and the SDK automatically manages the channel during usage. +Concurrent (prepaid) calls allow you to prepay for a batch of service calls in advance. This off-chain strategy +is ideal for scenarios requiring high throughput and low latency. Unlike regular paid calls, the payment is done +once upfront, and the SDK automatically manages the channel during usage. -To use concurrent prepaid calls, specify the `concurrent_calls` parameter when creating a service client: +If you want to use prepaid calls you will need to choose `PaymentStrategyType.PREPAID_CALL` as the payment strategy type +as well as pass the number of concurrent calls as the `concurrent_calls` parameter. Creating a service client with +prepaid calls would look like this: ```python service_client = snet_sdk.create_service_client( org_id="26072b8b6a0e448180f8c0e702ab6d2f", service_id="Exampleservice", group_name="default_group", + payment_strategy_type=PaymentStrategyType.PREPAID_CALL, concurrent_calls=5 # Number of prepaid calls to allocate ) ``` diff --git a/docs/main/init.md b/docs/main/init.md index 1436cc5..223b956 100644 --- a/docs/main/init.md +++ b/docs/main/init.md @@ -3,7 +3,8 @@ [Link](https://github.com/singnet/snet-sdk-python/blob/master/snet/sdk/__init__.py) to GitHub Entities: -1. [SnetSDK](#class-snetsdk) +1. [PaymentStrategyType](#class-paymentstrategytype) +2. [SnetSDK](#class-snetsdk) - [\_\_init\_\_](#__init__) - [create_service_client](#create_service_client) - [get_service_stub](#get_service_stub) @@ -15,6 +16,24 @@ Entities: - [get_organization_list](#get_organization_list) - [get_services_list](#get_services_list) +### Class `PaymentStrategyType` + +extends: `Enum` + +is extended by: - + +#### description + +This is an `enum` that represents the available payment strategies. It is used to determine which payment +strategy to use when initializing the SDK. + +#### members + +- `DEFAULT` +- `FREE_CALL` +- `PAID_CALL` +- `PREPAID_CALL` + ### Class `SnetSDK` extends: - @@ -73,7 +92,8 @@ of the `ServiceClient` class with all the required parameters, which is then ret - `service_id` (str): The ID of the service. - `group_name` (str): The name of the payment group. Defaults to _None_. - `payment_strategy` (PaymentStrategy): The payment channel management strategy. Defaults to _None_. -- `address` (str): Wallet address to use free calls. Defaults to _None_. +- `payment_strategy_type` (PaymentStrategyType): The type of payment management strategy. +Defaults to `PaymentStrategyType.DEFAULT`. - `options` (dict): Additional options for the service client. Defaults to _None_. - `concurrent_calls` (int): The number of concurrent calls allowed. Defaults to 1. diff --git a/docs/payment_strategies/freecall_payment_strategy.md b/docs/payment_strategies/freecall_payment_strategy.md index e6f5934..7bb48e5 100644 --- a/docs/payment_strategies/freecall_payment_strategy.md +++ b/docs/payment_strategies/freecall_payment_strategy.md @@ -4,11 +4,10 @@ Entities: 1. [FreeCallPaymentStrategy](#class-freecallpaymentstrategy) - - [is_free_call_available](#is_free_call_available) + - [get_free_calls_available](#get_free_calls_available) - [get_payment_metadata](#get_payment_metadata) - [generate_signature](#generate_signature) - [get_free_call_token_details](#get_free_call_token_details) - - [select_channel](#select_channel) ### Class `FreeCallPaymentStrategy` @@ -24,9 +23,10 @@ call services. #### methods -#### `is_free_call_available` +#### `get_free_calls_available` -Checks if a free call is available for a given service client. +Using grpc calls to the daemon, it gets a free call token, and also gets and returns the number of free calls +available. ###### args: @@ -34,13 +34,13 @@ Checks if a free call is available for a given service client. ###### returns: -- True if a free call is available, False otherwise. (bool) +- Amount of free calls available. (int) ###### raises: - Exception: If an error occurs while checking the free call availability. -_Note_: If any exception occurs during the process, it returns False. +_Note_: If an error occurs specifically during the grpc call to `GetFreeCallsAvailable`, 0 will be returned. #### `get_payment_metadata` @@ -62,6 +62,8 @@ Generates a signature for the given service client using the provided free call ###### args: - `service_client` (ServiceClient): The service client instance. +- `current_block_number` (int, optional): The current block number. Defaults to _None_. +- `with_token` (bool, optional): Whether to include the free call token in the signature. Defaults to _True_. ###### returns: @@ -73,11 +75,12 @@ Generates a signature for the given service client using the provided free call #### `get_free_call_token_details` -Sends a request to the daemon and receives a free call token. +Sends a request to the daemon and receives a free call token and its details. ###### args: - `service_client` (ServiceClient): The service client instance. +- `current_block_number` (int, optional): The current block number. Defaults to _None_. ###### returns: @@ -86,15 +89,3 @@ Sends a request to the daemon and receives a free call token. ###### raises: - Exception: If an error occurred while receiving the token. - -#### `select_channel` - -Creates a channel to the daemon. - -###### args: - -- `service_client` (ServiceClient): The service client object. - -###### returns: - -- The channel for the service calling. \ No newline at end of file diff --git a/snet/sdk/__init__.py b/snet/sdk/__init__.py index 89a2585..d35a77e 100644 --- a/snet/sdk/__init__.py +++ b/snet/sdk/__init__.py @@ -105,7 +105,6 @@ def create_service_client(self, group_name: str=None, payment_strategy: PaymentStrategy = None, payment_strategy_type: PaymentStrategyType=PaymentStrategyType.DEFAULT, - address=None, options=None, concurrent_calls: int = 1): @@ -132,7 +131,6 @@ def create_service_client(self, if options is None: options = dict() - options['user_address'] = address if address else "" options['concurrency'] = self._sdk_config.get("concurrency", True) options['concurrent_calls'] = concurrent_calls diff --git a/snet/sdk/service_client.py b/snet/sdk/service_client.py index a223fab..9e367b6 100644 --- a/snet/sdk/service_client.py +++ b/snet/sdk/service_client.py @@ -214,11 +214,6 @@ def generate_training_signature(self, text: str, address: str, defunct_hash_message(message), self.account.signer_private_key ).signature - def get_free_call_config(self) -> tuple[str, str, int]: - return (self.options['email'], - self.options['free_call_auth_token-bin'], - self.options['free-call-token-expiry-block']) - def get_service_details(self) -> tuple[str, str, str, str]: return (self.org_id, self.service_id,