safeheron-api-sdk-python 1.1.18__py3-none-any.whl

safeheron_api_sdk_python/api/webhook_api.py

@@ -0,0 +1,49 @@
+from safeheron_api_sdk_python.client import *
+
+class ResendWebhookRequest:
+    def __init__(self):
+        # Supported events:
+        # TRANSACTION
+        # MPC_SIGN
+        # WEB3_SIGN
+        self.category = None
+        # Transaction key
+        self.txKey = None
+
+class ResendFailedRequest:
+    def __init__(self):
+        # Start time in UNIX timestamp (ms). The time interval [startTime, endTime] is up to 1 hour
+        self.startTime = None
+        # End time in UNIX timestamp (ms). The time interval [startTime, endTime] is up to 1 hour
+        self.endTime = None
+
+
+class WebhookApi:
+
+    def __init__(self, config):
+        self.api_client = Client(config)
+    # Re-push Transaction Webhook Events
+    # Re-push the transaction webhook events generated in the last month. In certain situations, such as network jitter or your system being unavailable to receive webhook events, you may miss receiving notifications. You can use this interface to notify Safeheron to re-push the webhook events. It is important to note that for a single transaction, only the last webhook event will be re-pushed. For example, during the lifecycle of a transaction, multiple TRANSACTION_STATUS_CHANGED webhook events such as BROADCASTING, CONFIRMING, COMPLETED, etc., may be generated. The re-push will only send the last webhook event recorded by the current system. Re-pushing is supported for the following types of webhook events:
+    # Events related to asset transactions, including TRANSACTION_CREATED and TRANSACTION_STATUS_CHANGED.
+    # Events related to MPC signing, including MPC_SIGN_CREATED and MPC_SIGN_STATUS_CHANGED.
+    # Events related to Web3, including WEB3_SIGN_CREATED and WEB3_SIGN_STATUS_CHANGED.
+    # More types of webhook events will be supported in the future.
+    def resend_webhook(self, request: ResendWebhookRequest):
+        return self.api_client.send_request(request, '/v1/webhook/resend')
+
+    # Push All Failed Webhook Events
+    # Resend all webhook events that failed to push within any duration not exceeding 1 hour in the past 7 days (limited to 1 call every 10 minutes). In certain situations, such as network failures or your system being unavailable to receive webhook events, you may miss receiving notifications. Once the issue is resolved, you can use this interface to notify Safeheron to resend all webhook events that failed to push within a certain period. Support re-pushing the following types of webhook events:
+    # TRANSACTION_CREATED
+    # TRANSACTION_STATUS_CHANGED
+    # MPC_SIGN_CREATED
+    # MPC_SIGN_STATUS_CHANGED
+    # WEB3_SIGN_CREATED
+    # WEB3_SIGN_STATUS_CHANGED
+    # ILLEGAL_IP_REQUEST
+    # NO_MATCHING_TRANSACTION_POLICY
+    # More types of webhook events will be supported in the future.
+    # Please note that when re-pushing all failed webhook events, your system needs to avoid rollback issues. For example, during the lifecycle of a transaction, multiple TRANSACTION_STATUS_CHANGED webhook events may be generated, such as BROADCASTING, CONFIRMING, and COMPLETED. If your system did not receive the CONFIRMING event due to network issues but did receive the COMPLETED event, using this interface would cause Safeheron to attempt resending the CONFIRMING event to your system. Your system needs to ensure that the transaction does not incorrectly revert from the COMPLETED status back to the CONFIRMING status.
+    def resend_failed(self, request: ResendFailedRequest):
+        return self.api_client.send_request(request, '/v1/webhook/resend/failed')
+
+

safeheron_api_sdk_python/api/whitelist_api.py

@@ -0,0 +1,154 @@
+from safeheron_api_sdk_python.client import *
+
+
+class ListWhitelistRequest:
+    def __init__(self):
+        # Query page direction, NEXT by default
+        self.direct = None
+        # The number of items to retrieve at a time, default max value is 500
+        self.limit = None
+        # Txkey of the first transaction record. If the first page has no value, provide the txKey of the last transaction record from the previous result
+        self.fromId = None
+        # The supported public blockchains for whitelist addresses are:
+        # EVM: Ethereum-compatible public chain networks or Layer 2 addresses that can receive its native token and other tokens
+        # Bitcoin: Bitcoin mainnet addresses that can receive Bitcoin
+        # Bitcoin Cash: Bitcoin Cash network, which can receive BCH
+        # Dash: anonymous Dash network, which can receive DASH
+        # TRON: Tron mainnet addresses, which can receive TRX and TRC20 tokens, such as USDT and USDC
+        # NEAR: NEAR mainnet, which can receive native token NEAR
+        # Filecoin: Receive Filecoin native token FIL, but does not support receiving FIL or tokens from the FVM network
+        # Sui: Sui mainnet, which can receive native token Sui and other tokens
+        # Aptos: Aptos mainnet, which only supports receiving native token Aptos and does not support other tokens yet
+        # Solana: Solana mainnet, which can receive native token SOL and other tokens
+        # Bitcoin Testnet: Bitcoin testnet, which can receive Bitcoin testnet ass
+        self.chainType = None
+        # Whitelist status
+        # AUDIT: pending approval
+        # APPROVED: active
+        # REJECTED: rejected
+        self.whitelistStatus = None
+        # Start time for creating a whitelist in UNIX timestamp (ms) (If no value is provided, the default value is createTimeMax minus 24 hours)
+        self.createTimeMin = None
+        # End time for creating a whitelist in UNIX timestamp (ms) (If no value is provided, the default value is the current UTC time)
+        self.createTimeMax = None
+
+
+class OneWhitelistRequest:
+    def __init__(self):
+        # Whitelist unique identifier. It is required if address is not provided. If both are provided, the whitelistKey takes precedence
+        self.whitelistKey = None
+        # Whitelist address. It is required if whitelistKey is not provided and please make sure the provided address is correct
+        self.address = None
+
+
+class CreateWhitelistRequest:
+    def __init__(self):
+        # Whitelist unique name, 20 characters max
+        self.whitelistName = None
+        # The supported public blockchains for whitelist addresses are:
+        # EVM: Ethereum-compatible public chain networks or Layer 2 addresses that can receive its native token and other tokens
+        # Bitcoin: Bitcoin mainnet addresses that can receive Bitcoin
+        # Bitcoin Cash: Bitcoin Cash network, which can receive BCH
+        # Dash: anonymous Dash network, which can receive DASH
+        # TRON: Tron mainnet addresses, which can receive TRX and TRC20 tokens, such as USDT and USDC
+        # NEAR: NEAR mainnet, which can receive native token NEAR
+        # Filecoin: Receive Filecoin native token FIL, but does not support receiving FIL or tokens from the FVM network
+        # Sui: Sui mainnet, which can receive native token Sui and other tokens
+        # Aptos: Aptos mainnet, which only supports receiving native token Aptos and does not support other tokens yet
+        # Solana: Solana mainnet, which can receive native token SOL and other tokens
+        # Bitcoin Testnet: Bitcoin testnet, which can receive Bitcoin testnet assets
+        self.chainType = None
+        # Public blockchain address and the address format needs to meet the requirements of the chain
+        self.address = None
+        #  The memo (up to 20 characters) for the destination address, also known as a comment or tag. For the following networks, if a destination address memo was set initially, a memo matching the one in the transaction record must be provided
+        #  TON: TON mainnet
+        #  TON_TESTNET: TON testnet
+        self.memo = None
+        # Visibility status in Safeheron App and Web Console
+        # False: Visible by default
+        # True: Invisible; the invisible whitelist can only be managed and used through the API, such as querying, modifying, and using the whitelist as the destination address when initiating transactions
+        self.hiddenOnUI = None
+
+
+class CreateFromTransactionWhitelistRequest:
+    def __init__(self):
+        # Whitelist unique name, 20 characters max
+        self.whitelistName = None
+        # Transaction key
+        self.txKey = None
+        # The destination address in the transaction record; case-sensitive
+        self.destinationAddress = None
+        #  The memo (up to 20 characters) for the destination address, also known as a comment or tag. For the following networks, if a destination address memo was set initially, a memo matching the one in the transaction record must be provided
+        #  TON: TON mainnet
+        #  TON_TESTNET: TON testnet
+        self.memo = None
+        # Visibility status in Safeheron App and Web Console
+        # False: Visible by default
+        # True: Invisible; the invisible whitelist can only be managed and used through the API, such as querying, modifying, and using the whitelist as the destination address when initiating transactions
+        self.hiddenOnUI = None
+
+
+class EditWhitelistRequest:
+    def __init__(self):
+        # Whitelist unique identifier
+        self.whitelistKey = None
+        # Whitelist unique name, 20 characters max
+        self.whitelistName = None
+        # Public blockchain address and the address format needs to meet the requirements of the chain
+        self.address = None
+        #  The memo (up to 20 characters) for the destination address, also known as a comment or tag. For the following networks, if a destination address memo was set initially, a memo matching the one in the transaction record must be provided
+        #  TON: TON mainnet
+        #  TON_TESTNET: TON testnet
+        self.memo = None
+        # When the whitelist is involved in a transaction approval policy, modifications will result in the new whitelist being directly applied to the approval policy. False by default, meaning that when involved in a transaction approval policy, it will not be modified.
+        self.force = None
+
+
+class DeleteWhitelistRequest:
+    def __init__(self):
+        # Whitelist unique identifier
+        self.whitelistKey = None
+
+
+class WhitelistApi:
+
+    def __init__(self, config):
+        self.api_client = Client(config)
+
+    # List Whitelist Data
+    # Paginate the whitelist data based on the query criteria.
+    def list_whitelist(self, request: ListWhitelistRequest):
+        return self.api_client.send_request(request, '/v1/whitelist/list')
+
+    # Retrieve a Single Whitelist
+    #      * Retrieve the data of a whitelist.
+    def one_whitelist(self, request: OneWhitelistRequest):
+        return self.api_client.send_request(request, '/v1/whitelist/one')
+
+    # Create a Whitelist
+    # Add a new whitelisted address. The newly added address needs to be approved in the Safeheron App before it becomes effective. The approval details are as follows:
+    # Admin approval: If a custom whitelist approval process is not set, it will become effective after being approved by the team admins according to the team's decision-making process.
+    # Custom whitelist approval: If a whitelist approval process is set, it will become effective after being approved according to the process.
+    def create_whitelist(self, request: CreateWhitelistRequest):
+        return self.api_client.send_request(request, '/v1/whitelist/create')
+
+    # Create a Whitelist Based on a Transaction
+    # Whitelist the transaction's destination address when the transaction meets the following conditions:
+    #
+    # A transfer transaction from an asset wallet; Web3 wallet transactions or MPC Sign transactions are not supported.
+    # The transaction is in a completed state as COMPLETED.
+    # The transaction's destination address is a one-time address.
+    def create_from_transaction_whitelist(self, request: CreateFromTransactionWhitelistRequest):
+        return self.api_client.send_request(request, '/v1/whitelist/createFromTransaction')
+
+    # Modify a Whitelist
+    # Modify a whitelist based on its unique identifier. The whitelist only supports modifying its name and address; whitelists pending for approval cannot be modified. After modifying the whitelist, it needs to be reviewed and approved in the Safeheron App before it becomes effective. The approval details are as follows:
+    # Admin approval: If a custom whitelist approval process is not set, it will become effective after being approved by the team admins according to the team's decision-making process.
+    # Custom whitelist approval: If a whitelist approval process is set, it will become effective after being approved according to the process.
+    def edit_whitelist(self, request: EditWhitelistRequest):
+        return self.api_client.send_request(request, '/v1/whitelist/edit')
+
+    # Delete a Whitelist
+    # To delete a whitelisted address, note that no approval is required for deletion. If a whitelisted address that is under approval is deleted, the approval task will also be automatically cancelled.
+    def delete_whitelist(self, request: DeleteWhitelistRequest):
+        return self.api_client.send_request(request, '/v1/whitelist/delete')

safeheron_api_sdk_python/client.py

@@ -0,0 +1,28 @@
+from safeheron_api_sdk_python.tools import *
+
+
+class Client:
+
+    def __init__(self, config):
+        self.api_key = config['apiKey']
+        self.platform_pub_key = config['safeheronPublicKey']
+        self.base_url = config['baseUrl']
+        if config.get('requestTimeout'):
+            self.requestTimeout = config['requestTimeout'] / 1000
+        else:
+            self.requestTimeout = 20
+        if config.get('privateKey'):
+            self.use_private_key = PEM_PRIVATE_HEAD + config['privateKey'] + PEM_PRIVATE_END
+        if config.get('privateKeyPemFile'):
+            self.use_private_key = load_rsa_private_key(config['privateKeyPemFile'])
+
+    def send_request(self, request, uri):
+        req = encrypt_request(self.api_key, request, self.platform_pub_key, self.use_private_key)
+        res = self.execution(req, uri)
+        res.raise_for_status()
+        res = res.json()
+        return decrypt_response(res, self.platform_pub_key, self.use_private_key)
+
+    def execution(self, request, uri):
+        return requests.post(self.base_url + uri, data=json.dumps(request), headers={"Content-Type": "application/json"},
+                             timeout=self.requestTimeout)

safeheron_api_sdk_python/cosigner/co_signer_converter.py

@@ -0,0 +1,185 @@
+from safeheron_api_sdk_python.tools import *
+
+
+class CoSignerResponse:
+    def __init__(self):
+        # approve
+        self.approve = None
+        # txKey
+        self.txKey = None
+
+
+class CoSignerResponseV3:
+    def __init__(self):
+        # action
+        self.action = None
+        # approvalId
+        self.approvalId = None
+
+
+class CoSignerConverter:
+
+    def __init__(self, config):
+        # Supports both coSignerPubKey and apiPublKey
+        self.co_signer_pub_key = config.get('coSignerPubKey') or config.get('apiPubKey')
+
+        # Supports both approvalCallbackServicePrivateKey and bizPrivKey
+        private_key = config.get('approvalCallbackServicePrivateKey') or config.get('bizPrivKey')
+        if private_key:
+            self.approval_callback_service_private_key = PEM_PRIVATE_HEAD + private_key + PEM_PRIVATE_END
+
+        # Supports both approvalCallbackServicePrivateKeyPemFile and bizPrivKeyPemFile
+        pem_file = config.get('approvalCallbackServicePrivateKeyPemFile') or config.get('bizPrivKeyPemFile')
+        if pem_file:
+            self.approval_callback_service_private_key = load_rsa_private_key(pem_file)
+
+    def request_convert(self, co_signer_call_back):
+        platform_rsa_pk = get_rsa_key(PEM_PUBLIC_HEAD + self.co_signer_pub_key + PEM_PUBLIC_END)
+        api_user_rsa_sk = get_rsa_key(self.approval_callback_service_private_key)
+        required_keys = {
+            'key',
+            'sig',
+            'bizContent',
+            'timestamp',
+        }
+
+        missing_keys = required_keys.difference(co_signer_call_back.keys())
+        if missing_keys:
+            raise Exception(co_signer_call_back)
+
+        # 1 rsa verify
+        rsaType = ''
+        if "rsaType" in co_signer_call_back:
+            rsaType = co_signer_call_back.pop('rsaType')
+
+        aesType = ''
+        if "aesType" in co_signer_call_back:
+            aesType = co_signer_call_back.pop('aesType')
+
+        sig = co_signer_call_back.pop('sig')
+        need_sign_message = sort_request(co_signer_call_back)
+        v = rsa_verify(platform_rsa_pk, need_sign_message, sig)
+        if not v:
+            raise Exception("rsa verify: false")
+
+        # 2 get aes key and iv
+        key = co_signer_call_back.pop('key')
+        if ECB_OAEP_TYPE == rsaType:
+            aes_data = rsa_oaep_decrypt(api_user_rsa_sk, key)
+        else:
+            aes_data = rsa_decrypt(api_user_rsa_sk, key)
+        aes_key = aes_data[0:32]
+        aes_iv = aes_data[32:48]
+
+        # 3 aes decrypt data, get response data
+        if GCM_TYPE == aesType:
+            r = aes_gcm_decrypt(aes_key, aes_iv, b64decode(co_signer_call_back['bizContent']))
+        else:
+            r = aes_decrypt(aes_key, aes_iv, b64decode(co_signer_call_back['bizContent']))
+        # response_dict['bizContent'] = json.loads(r.decode())
+
+        return json.loads(r.decode())
+
+    def request_v3_convert(self, co_signer_call_back):
+        platform_rsa_pk = get_rsa_key(PEM_PUBLIC_HEAD + self.co_signer_pub_key + PEM_PUBLIC_END)
+        required_keys = {
+            'version',
+            'sig',
+            'bizContent',
+            'timestamp',
+        }
+
+        missing_keys = required_keys.difference(co_signer_call_back.keys())
+        if missing_keys:
+            raise Exception(co_signer_call_back)
+        co_signer_call_back['version'] = 'v3'
+        sig = co_signer_call_back.pop('sig')
+
+        need_sign_message = sort_request(co_signer_call_back)
+        v = rsa_pass_verify(platform_rsa_pk, need_sign_message, sig)
+        if not v:
+            raise Exception("rsa verify: false")
+        return json.loads(b64decode(co_signer_call_back['bizContent']).decode())
+
+    def response_v3_converter(self, co_signer_response: CoSignerResponseV3):
+        api_user_rsa_sk = get_rsa_key(self.approval_callback_service_private_key)
+        ret = dict()
+        response_data = json.dumps(co_signer_response.__dict__).replace('\'', '\"').replace('\n', '').encode('utf-8')
+
+        if response_data is not None:
+            ret['bizContent'] = b64encode(response_data).decode()
+
+        ret['timestamp'] = str(int(time.time() * 1000))
+        ret['code'] = str('200')
+        ret['version'] = str('v3')
+        ret['message'] = str('SUCCESS')
+
+        # 4 sign request
+        need_sign_message = sort_request(ret)
+        ret['sig'] = rsa_pss_sign(api_user_rsa_sk, need_sign_message)
+        return ret
+
+
+    # It has been Deprecated,Please use convertCoSignerResponseWithNewCryptoType
+    def response_converter(self, co_signer_response: CoSignerResponse):
+        platform_rsa_pk = get_rsa_key(PEM_PUBLIC_HEAD + self.co_signer_pub_key + PEM_PUBLIC_END)
+        api_user_rsa_sk = get_rsa_key(self.approval_callback_service_private_key)
+
+        ret = dict()
+
+        # prepare aes key and iv
+        aes_key = get_random_bytes(32)
+        aes_iv = get_random_bytes(16)
+        response_data = json.dumps(co_signer_response.__dict__).replace('\'', '\"').replace('\n', '').encode('utf-8')
+
+        # 1 rsa encrypt aes key + iv
+        aes_data = aes_key + aes_iv
+        ret['key'] = rsa_encrypt(platform_rsa_pk, aes_data)
+
+        # 2 aes encrypt request data
+        if response_data is not None:
+            aes_encrypted_bytes = aes_encrypt(aes_key, aes_iv, response_data)
+            ret['bizContent'] = b64encode(aes_encrypted_bytes).decode()
+
+        # 3 set timestamp
+        ret['timestamp'] = str(int(time.time() * 1000))
+        ret['code'] = str('200')
+        ret['message'] = str('SUCCESS')
+
+        # 4 sign request
+        need_sign_message = sort_request(ret)
+        ret['sig'] = rsa_sign(api_user_rsa_sk, need_sign_message)
+
+        return ret
+
+    def response_converter_with_new_crypto_type(self, co_signer_response: CoSignerResponse):
+        platform_rsa_pk = get_rsa_key(PEM_PUBLIC_HEAD + self.co_signer_pub_key + PEM_PUBLIC_END)
+        api_user_rsa_sk = get_rsa_key(self.approval_callback_service_private_key)
+
+        ret = dict()
+
+        # prepare aes key and iv
+        aes_key = get_random_bytes(32)
+        aes_iv = get_random_bytes(16)
+        response_data = json.dumps(co_signer_response.__dict__).replace('\'', '\"').replace('\n', '').encode('utf-8')
+
+        # 1 rsa encrypt aes key + iv
+        aes_data = aes_key + aes_iv
+        ret['key'] = rsa_oaep_encrypt(platform_rsa_pk, aes_data)
+
+        # 2 aes encrypt request data
+        if response_data is not None:
+            aes_encrypted_bytes = aes_gcm_encrypt(aes_key, aes_iv, response_data)
+            ret['bizContent'] = b64encode(aes_encrypted_bytes).decode()
+
+        # 3 set timestamp
+        ret['timestamp'] = str(int(time.time() * 1000))
+        ret['code'] = str('200')
+        ret['message'] = str('SUCCESS')
+
+        # 4 sign request
+        need_sign_message = sort_request(ret)
+        ret['sig'] = rsa_sign(api_user_rsa_sk, need_sign_message)
+        ret['rsaType'] = ECB_OAEP_TYPE
+        ret['aesType'] = GCM_TYPE
+        return ret