Metadata-Version: 2.1
Name: kin-sdk
Version: 2.4.3
Summary: KIN SDK for Python
Home-page: https://github.com/kinecosystem/kin-sdk-python/tree/v2-master
Author: Kin Ecosystem
Author-email: david.bolshoy@kik.com
Maintainer: Ron Serruya
Maintainer-email: ron.serruya@kik.com
License: MIT
Description: ![Kin Logo](kin.png)
        
        # KIN Python SDK for Kin Blockchain
        
        ## Requirements.
        
        Python >= 3.6
        
        ## Installation 
        
        ```bash
        pip install kin-sdk
        ```
        
        ## Usage
        
        ### Initialization
        
        The sdk has two main components, KinClient and KinAccount.
        **KinClient** - Used to query the blockchain and perform actions that don't require authentication (e.g Get account balance)
        **KinAccount** - Used to perform authenticated actions on the blockchain (e.g Send payment)
        
        To initialize the Kin Client you will need to provide an environment (Test and Production environments are pre-configured)
        The KinClient object can be used with a context manager, or closed manually, to close the connection to the blockchain
        
        ```python
        from kin import KinClient, TEST_ENVIRONMENT
        
        async with KinClient(TEST_ENVIRONMENT) as client:
           ...
        
        OR
        
        client = KinClient(TEST_ENVIRONMENT)
        try:
           ...
        finally:
           client.close()
        
        ```
        
        Custom environment can also be used:  
        ```python
        from kin import Environment
        
        MY_CUSTOM_ENVIRONMENT = Environemnt('name','horizon endpoint','network passphrase','friendbot url'(optional))
        ```
        
        Once you have a KinClient, you can use it to get a KinAccount object: 
        ```python
        # The KinAccount object can be initizlied in two ways:
        
        # With a single seed:
        account = client.kin_account('seed')
        
        # With channels:
        account = client.kin_account('seed', channel_secret_keys=['seed1','seed2','seed3'...])
        
        # Additionaly, an unique app-id can be provided, this will mark all of your transactions and allow the Kin Ecosystem to track the kin usage of your app
        # A unique app-id should be received from the Kin Ecosystem
        account = client.kin_account('seed',app_id='unique_app_id')
        ```
        Read more about channels in the ["Channels" section](#Channels)
        
        ## Client Usage
        Most methods provided by the KinClient to query the blockchain about a specific account, can also be used from the KinAccount object to query the blockchain about itself
        
        ### Getting Account Balance
        ```python
        # Get KIN balance
        balance = await client.get_account_balance('address')
        ```
        
        ### Getting Account Data
        ```python
        account_data = await client.get_account_data('address')
        ```
        
        ### Checking If an account exists on the blockchain
        ```python
        await client.does_account_exists('address')
        ```
        
        ### Getting the minimum acceptable fee from the blockchain
        Transactions usually require a fee to be processed.
        To know what is the minimum fee that the blockchain will accept, use:
        ```python
        minimum_fee = await client.get_minimum_fee()
        ```
        
        ### Getting Transaction Data
        Get information about a specific transaction
        The 'simple' flag is enabled by default, and dictates what object should be returned
        For simple=False: A 'kin.RawTransaction' object will return,
        containing some fields that may be confusing and of no use to the user.
        
        For simple=True: A 'kin.SimpleTransaction' object will return,
        containing only the data that the user will need.
        However, if the transaction if too complex to be simplified, a 'CantSimplifyError' will be raised
        ```python
        tx_data = await sdk.get_transaction_data(tx_hash, simple=True/False)
        ```
        
        
        A transaction will not be simplified if:
        1. It contains a memo that is not a text memo
        2. It contains multiple operations
        3. It contains a payment that is not of KIN
        4. Its operation type is not one of 'Payment'/'Create account'.
        
        Given the use case of our blockchain, and the tools that we currently provide to interact with it, these conditions should not usually occur.
        
        ### Checking configuration
        The handy `get_config` method will return some parameters the client was configured with, along with Horizon status:
        ```python
        status = client.get_config()
        ```
        
        ```json
            {
          "sdk_version": "2.4.0",
          "environment": "TEST",
          "horizon": {
            "uri": "https://horizon-testnet.kininfrastructure.com",
            "online": true,
            "error": null
          },
          "transport": {
            "pool_size": 100,
            "num_retries": 3,
            "request_timeout": 11,
            "backoff_factor": 0.5
          }
        }
        ```
        - `sdk_version` - the version of this SDK.
        - `environment` - the environment the SDK was configured with (TEST/PROD/CUSTOM).
        - `horizon`:
          - `uri` - the endpoint URI of the Horizon server.
          - `online` - Horizon online status.
          - `error` - Horizon error (when not `online`) .
        - `transport`:
          - `pool_size` - number of pooled connections to Horizon.
          - `num_retries` - number of retries on failed request.
          - `request_timeout` - single request timeout.
          - `backoff_factor` - a backoff factor to apply between retry attempts.
        
        
        ### Friendbot
        If a friendbot endpoint is provided when creating the environment (it is provided with the TEST_ENVIRONMENT),
        you will be able to use the friendbot method to call a service that will create an account for you
        ```python
        await client.friendbot('address')
        ```
        
        Additionally, you may also use the friendbot to request KIN for testing
        ```python
        await client.friendbot_fund('address', amount) # Up to 10K KIN
        ```
        
        
        ## Account Usage
        
        ### Getting Wallet Details
        Get the public address of my wallet account. The address is derived from the seed the account was created with.
        ```python
        address = account.get_public_address()
        ```
        
        ### Creating a New Account
        Create a new account
        the KIN amount can be specified in numbers or as a string
        ```python
        tx_hash = await account.create_account('address', starting_balance=1000, fee=100)
        ```
        A text memo can also be provided:
        ```python
        tx_hash = await account.create_account('address', starting_balance=1000, fee=100, memo_text='Account creation')
        ```
        
        ### Sending KIN
        The KIN amount can be specified in numbers or as a string
        ```python
        tx_hash = await account.send_kin('destination', 1000, fee=100, memo_text='order123')
        ```
        
        ### Build/Submit transactions
        While the previous methods build and send the transaction for you, there is another way to send transactions
        
        Step 1: Build the transaction
        ```python
        builder = account.build_send_kin('destination', 1000, fee=100, memo_text='order123')
        ```
        Step 2: Update the transaction
        ```python
        # do whatever you want with the builder
        async with account.channel_manager.get_channel() as channel:
            await builder.set_channel(channel)
            builder.sign(channel)
            # If you used additional channels apart from your main account,
            # sign with your main account
            builder.sign(account.keypair.secret_seed)
        ```
        Step 3: Send the transaction
        ```python
            tx_hash = await account.submit_transaction(builder)
        ```
        
        ### Whitelist a transaction
        Assuming you are registered as a whitelisted digital service with the Kin Ecosystem (exact details TBD)
        You will be able to whitelist transactions for your clients, making it so that their fee will not be deducted
        Your clients will send an http request to you containing their tx.
        You can then whitelist it, and return it back to the client to send to the blockchain
        ```python
        whitelisted_tx = account.whitelist_transaction(client_transaction)
        
        # By defualt, any payment sent from you is already considered whitelisted,
        # so there is no need for this step for the server transactions
        ```
        
        ### Get account status
        Get the status and config of the account
        If verbose it set to true, all channels and statuses will be printed
        ```python
        account.get_status(verbose=False/True)
        ```
        
        ```json
        {
          "client": {
            "sdk_version": "2.4.0",
            "environment": "TEST",
            "horizon": {
              "uri": "https://horizon-testnet.kininfrastructure.com",
              "online": true,
              "error": null
            },
            "transport": {
              "pool_size": 100,
              "num_retries": 3,
              "request_timeout": 11,
              "backoff_factor": 0.5
            }
          },
          "account": {
            "app_id": "anon",
            "public_address": "GBQLWHAH5BRB3PTJEXIKGKI3YYM2DJI32ZOZBR4O5WE7FE2GNSUTF6RP",
            "balance": 10000,
            "channels": {
              "total_channels": 5,
              "free_channels": 4,
              "non_free_channels": 1,
              "channels": {
                "SBRHUVGBCXDM2HDSTQ5Y5QLMBCTOTK6GIQ4PDZIMCD3SG3A7MU22ASRV": "free",
                "SA6XIHKGWVGUNOWUPCEA2SWBII5JEHK7Q54I2ESZ42NKUX5NYNXPTA4P": "free",
                "SB57K5N2JUVXBF3S56OND4WXLZAXMBB7WFV5E5ZQTHOGQQTGCY4ZBWGL": "free",
                "SCFXWAXZHM3OJA5XJNW4MIDPRYZHTECXJEOYY5O6JJB523M32OJXD756": "taken",
                "SA6YK4SR2KS2RXV7SN6HFVXNO44AA7IQTZ7QKWAWS6TPJ2NCND2JMLY3": "free"
              }
            }
          }
        }
        ```
        
        ## Transactions
        These methods are relevant to transactions
        
        ### Decode_transaction
        When the client sends you a transaction for whitelisting, it will be encoded.
        If you wish to decode the transaction and verify its details before whitelisting it:
        
        ```python
        from kin import decode_transaction
        
        decoded_tx = decode_transaction(encoded_tx)
        ```
        
        ## Keypair
        These set of methods allow you to create new keypairs.
        
        ### Create a new keypair
        ```python
        from kin import Keypair
        
        my_keypair = Keypair()
        ```
        Or, you can create a keypair from an existing seed
        ```python
        my_keypair = Keypair('seed')
        ```
        
        ### Getting the public address from a seed
        ```python
        public_address = Keypair.address_from_seed('seed')
        ```
        
        ### Generate a new random seed
        ```python
        seed = Keypair.generate_seed()
        ```
        
        ### Generate a deterministic seed
        Given the same seed and salt, the same seed will always be generated
        ```python
        seed = Keypair.generate_hd_seed('seed','salt')
        ```
        
        ## Monitoring Kin Payments
        These methods can be used to monitor the kin payment that an account or accounts is sending/receiving
        ### Monitor a single account
        Monitoring a single account will continuously get data about this account from the blockchain and filter it.
        An additional "timeout" parameter can be passed to raise a "TimeoutError" if too much time passes between each tx.
        ```python
        async for tx in client.monitor_account_payments('address'):
           ...
        ```
        
        ### Monitor multiple accounts
        Monitoring multiple accounts will continuously get data about **all** accounts on the blockchain, and will filter it to only yield txs for the relevant accounts.
        Since this monitor receives a set of addresses, you can freely add/remove address at from it at any point
        ```python
        addresses = set(['address1','address2'])
        async for address, tx in client.monitor_accounts_payments(addresses):
           ...
        ```
        
        ## Channels
        
        One of the most sensitive points in Stellar is [transaction sequence](https://www.stellar.org/developers/guides/concepts/transactions.html#sequence-number).
        In order for a transaction to be submitted successfully, this number should be correct. However, if you have several 
        SDK instances, each working with the same wallet account or channel accounts, sequence collisions will occur. 
         
        We highly recommend to keep only one KinAccount instance in your application, having unique channel accounts.
        Depending on the nature of your application, here are our recommendations:
        
        1. You have a simple (command line) script that sends transactions on demand or only once in a while. 
        In this case, the SDK can be instantiated with only the wallet key, the channel accounts are not necessary.
        
        2. You have a single application server that should handle a stream of concurrent transactions. In this case, 
        you need to make sure that only a single instance of a KinAccount initialized with multiple channel accounts.
        
        3. You have a number of load-balanced application servers. Here, each application server should a) have the setup outlined
        above, and b) have its own channel accounts. This way, you ensure you will not have any collisions in your transaction
        sequences.
        
        ### Creating Channels
        The kin sdk allows you to create HD (highly deterministic) channels based on your seed and a passphrase to be used as a salt.
        As long as you use the same seed and passphrase, you will always get the same seeds.
        
        ```
        import kin.utils
        
        channels = utils.create_channels(master_seed, environment, amount, starting_balance, salt)
        
        # "channels" will be a list of seeds the sdk created for you, that can be used when initializing the KinAccount object.
        ```
        If you just wish to get the list of the channels generated from your seed + passphrase combination without creating them
        ```python
        channels = utils.get_hd_channels(master_seed, salt, amount)
        ```
        
        
        ## License
        The code is currently released under [Kin Ecosystem SDK License](LICENSE.pdf).
        
        
        ## Contributing
        See [CONTRIBUTING.md](CONTRIBUTING.md) for SDK contributing guidelines. 
        
        
        
Keywords: kin,stellar,blockchain,cryptocurrency
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.6
Description-Content-Type: text/markdown
