#
# Python Sygna Bridge Util
This is a Python library to help you build servers/services within Sygna Bridge Ecosystem. For more detail information, please see [Sygna Bridge](https://www.sygna.io/).
## Installation
```shell
pip install sygna-bridge-util
```
## Crypto
Dealing with encoding, decoding, signing and verifying in Sygna Bridge.
### ECIES Encoding an Decoding
During the communication of VASPs, there are some private information that must be encrypted. We use ECIES(Elliptic Curve Integrated Encryption Scheme) to securely encrypt these private data so that they can only be accessed by the recipient.
We're using [IVMS101 (interVASP Messaging Standard)](https://intervasp.org/) as our private information format.
We also provide [IVMS101 Python Utility](https://github.com/CoolBitX-Technology/sygna-bridge-ivms-utils/tree/master/python) to construct data payload.
```python
sensitive_data = {
"originator": {
"originator_persons": [
{
"natural_person": {
"name": {
"name_identifiers": [
{
"primary_identifier": "Wu Xinli",
"name_identifier_type": "LEGL"
}
]
},
"national_identification": {
"national_identifier": "446005",
"national_identifier_type": "RAID",
"registration_authority": "RA000553"
},
"country_of_residence": "TZ"
}
}
],
"account_numbers": [
"r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV"
]
},
"beneficiary": {
"beneficiary_persons": [
{
"legal_person": {
"name": {
"name_identifiers": [
{
"legal_person_name": "ABC Limited",
"legal_person_name_identifier_type": "LEGL"
}
]
}
}
}
],
"account_numbers": [
"rAPERVgXZavGgiGv6xBgtiZurirW2yAmY"
]
}
}
private_info = sygna_bridge_util.crypto.encrypt_private_data(
sensitive_data,
recipient_public_key
)
decoded_priv_info = sygna_bridge_util.crypto.decrypt_private_data(
private_info,
recipient_private_key
)
```
### Sign and Verify
In Sygna Bridge, we use secp256k1 ECDSA over sha256 of utf-8 json string to create signature on every API call. Since you need to provide the identical utf-8 string during verification, the order of key-value pair you put into the object is important.
The following example is the snippet of originator's signing process of `permissionRequest` API call. If you put the key `transaction` before `private_info` in the object, the verification will fail in the central server.
```python
transaction = {
"originator_vasp": {
"vasp_code": "VASPUSNY1",
"addrs": [
{
"address": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
"addr_extra_info": []
}
]
},
"beneficiary_vasp": {
"vasp_code": "VASPUSNY2",
"addrs": [
{
"address": "rAPERVgXZavGgiGv6xBgtiZurirW2yAmY",
"addr_extra_info": [
{
"tag": "abc"
}
]
}
]
},
"currency_id": "sygna:0x80000090",
"amount": "4.51120135938784"
}
data_dt = "2019-07-29T06:28:00Z"
# using sign_data to get a valid signed object (with signature attached)
data_to_sign = {
"private_info":private_info,
"transaction":transaction,
"data_dt":data_dt
}
sygna_bridge_util.crypto.sign_data(data_to_sign, originator_private_key)
valid = sygna_bridge_util.crypto.verify_data(obj, originator_public_Key)
# or you can use the method that's built for `transfer` request:
signed_data = sygna_bridge_util.crypto.sign_permission_request(
data_to_sign,
originator_private_key
)
valid = sygna_bridge_util.crypto.verify_data(
signed_data,
originator_public_Key
)
```
We provide different methods like `sign_permission_request`, `sign_callback()` to sign different objects(or parameters) we specified in our api doc. You can also find more examples in the following section.
## API
API calls to communicate with Sygna Bridge server.
We use **basic auth** with all the API calls. To simplify the process, we provide a API class to deal with authentication and post/ get request format.
```python=
sb_server = "https://api.sygna.io/"
sb_api_instance = sygna_bridge_util.API("api-key", sb_server)
```
After you create the `API` instance, you can use it to make any API call to communicate with Sygna Bridge central server.
### Get VASP Information
```python
# Get List of VASPs associated with public keys.
verify = True # set verify to true to verify the signature attached with api response automatically.
vasps = sb_api_instance.get_vasp_list(verify)
# Or call use get_vasp_public_key() to directly get public key for a specific VASP.
public_key = sb_api_instance.get_vasp_public_key("10298", verify)
```
### For Originator
There are two API calls from **transaction originator** to Sygna Bridge Server defined in the protocol, which are `post_permission_request` and `post_transaction_id`.
The full logic of originator would be like the following:
```python
# originator.py
recipient_public_key = sb_api_instance.get_vasp_public_key("10298")
private_info = sygna_bridge_util.crypto.sygna_encrypt_private_data(
# example from above
sensitive_data,
recipient_public_key
)
data_dt = "2019-07-29T07:29:80Z"
data_to_sign = {
"private_info":private_info,
# from example above
"transaction":transaction,
"data_dt":data_dt
}
transfer_data = sygna_bridge_util.crypto.sign_permission_request(
data_to_sign,
sender_privKey
)
callback_url = "https://81f7d956.ngrok.io/v2/originator/transaction/premission"
callback_data = sygna_bridge_util.crypto.sign_callback(
{
"callback_url":callback_url
},
sender_privKey
)
response = sb_api_instance.post_permission_request(
{
"data":transfer_data,
"callback":callback_data
}
)
# Broadcast your transaction to blockchain after got and api response at your api server.
txid = "1a0c9bef489a136f7e05671f7f7fada2b9d96ac9f44598e1bcaa4779ac564dcd"
# Inform Sygna Bridge that a specific transfer is successfully broadcasted to the blockchain.
send_tx_id_data = sygna_bridge_util.crypto.sign_transaction_id(
{
"transfer_id":response["transfer_id"],
"txid":txid
},
sender_privKey
)
post_tx_id_response = sb_api_instance.post_transaction_id(send_tx_id_data)
```
### For Beneficiary
There is only one api for Beneficiary VASP to call, which is `post_permission`. After the beneficiary server confirm their legitimacy of a transfer request, they will sign `{ transfer_id, permission_status }` using `sign_permission()` function, and send the result with signature to Sygna Bridge Central Server.
```Python
permission_status = "ACCEPTED" # or "REJECTED"
permission_data = sygna_bridge_util.crypto.sign_permission(
{
"transfer_id":response["transfer_id"],
"permission_status":permission_status
},
beneficiary_private_key
)
final_result = sb_api_instance.post_permission(permission_data)
```
For more complete example, please refer to [Example](example/main.py) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/CoolBitX-Technology/sygna-bridge-util-py",
"name": "sygna-bridge-util",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "",
"keywords": "sygna-bridge-util sygna bridge sygna-bridge ecosystem",
"author": "kunming.liu",
"author_email": "kunming@coolbitx.com",
"download_url": "https://files.pythonhosted.org/packages/03/48/17e9a17a6f241afc1b5d124baebb69a1d72c2d26b0dd1879a684b5d89283/sygna-bridge-util-2.0.3.tar.gz",
"platform": null,
"description": "# \n# Python Sygna Bridge Util\n\nThis is a Python library to help you build servers/services within Sygna Bridge Ecosystem. For more detail information, please see [Sygna Bridge](https://www.sygna.io/).\n\n## Installation\n\n\n```shell\npip install sygna-bridge-util\n```\n\n## Crypto\n\nDealing with encoding, decoding, signing and verifying in Sygna Bridge.\n\n### ECIES Encoding an Decoding\n\nDuring the communication of VASPs, there are some private information that must be encrypted. We use ECIES(Elliptic Curve Integrated Encryption Scheme) to securely encrypt these private data so that they can only be accessed by the recipient.\n\n\nWe're using [IVMS101 (interVASP Messaging Standard)](https://intervasp.org/) as our private information format.\n\nWe also provide [IVMS101 Python Utility](https://github.com/CoolBitX-Technology/sygna-bridge-ivms-utils/tree/master/python) to construct data payload.\n\n```python\nsensitive_data = {\n \"originator\": {\n \"originator_persons\": [\n {\n \"natural_person\": {\n \"name\": {\n \"name_identifiers\": [\n {\n \"primary_identifier\": \"Wu Xinli\",\n \"name_identifier_type\": \"LEGL\"\n }\n ]\n },\n \"national_identification\": {\n \"national_identifier\": \"446005\",\n \"national_identifier_type\": \"RAID\",\n \"registration_authority\": \"RA000553\"\n },\n \"country_of_residence\": \"TZ\"\n }\n }\n ],\n \"account_numbers\": [\n \"r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV\"\n ]\n },\n \"beneficiary\": {\n \"beneficiary_persons\": [\n {\n \"legal_person\": {\n \"name\": {\n \"name_identifiers\": [\n {\n \"legal_person_name\": \"ABC Limited\",\n \"legal_person_name_identifier_type\": \"LEGL\"\n }\n ]\n }\n }\n }\n ],\n \"account_numbers\": [\n \"rAPERVgXZavGgiGv6xBgtiZurirW2yAmY\"\n ]\n }\n}\n\nprivate_info = sygna_bridge_util.crypto.encrypt_private_data(\n sensitive_data, \n recipient_public_key\n)\ndecoded_priv_info = sygna_bridge_util.crypto.decrypt_private_data(\n private_info, \n recipient_private_key\n)\n\n```\n\n### Sign and Verify\n\nIn Sygna Bridge, we use secp256k1 ECDSA over sha256 of utf-8 json string to create signature on every API call. Since you need to provide the identical utf-8 string during verification, the order of key-value pair you put into the object is important.\n\nThe following example is the snippet of originator's signing process of `permissionRequest` API call. If you put the key `transaction` before `private_info` in the object, the verification will fail in the central server.\n\n```python\ntransaction = {\n \"originator_vasp\": {\n \"vasp_code\": \"VASPUSNY1\",\n \"addrs\": [\n {\n \"address\": \"r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV\",\n \"addr_extra_info\": []\n }\n ]\n },\n \"beneficiary_vasp\": {\n \"vasp_code\": \"VASPUSNY2\",\n \"addrs\": [\n {\n \"address\": \"rAPERVgXZavGgiGv6xBgtiZurirW2yAmY\",\n \"addr_extra_info\": [\n {\n \"tag\": \"abc\"\n }\n ]\n }\n ]\n },\n \"currency_id\": \"sygna:0x80000090\",\n \"amount\": \"4.51120135938784\"\n}\n\ndata_dt = \"2019-07-29T06:28:00Z\"\n\n# using sign_data to get a valid signed object (with signature attached)\n\ndata_to_sign = {\n \"private_info\":private_info,\n \"transaction\":transaction,\n \"data_dt\":data_dt\n}\n\nsygna_bridge_util.crypto.sign_data(data_to_sign, originator_private_key)\n\nvalid = sygna_bridge_util.crypto.verify_data(obj, originator_public_Key)\n\n# or you can use the method that's built for `transfer` request:\nsigned_data = sygna_bridge_util.crypto.sign_permission_request(\n data_to_sign, \n originator_private_key\n)\n\nvalid = sygna_bridge_util.crypto.verify_data(\n signed_data, \n originator_public_Key\n)\n\n```\n\nWe provide different methods like `sign_permission_request`, `sign_callback()` to sign different objects(or parameters) we specified in our api doc. You can also find more examples in the following section.\n\n## API\n\nAPI calls to communicate with Sygna Bridge server.\n\nWe use **basic auth** with all the API calls. To simplify the process, we provide a API class to deal with authentication and post/ get request format.\n\n```python=\nsb_server = \"https://api.sygna.io/\"\nsb_api_instance = sygna_bridge_util.API(\"api-key\", sb_server)\n```\n\nAfter you create the `API` instance, you can use it to make any API call to communicate with Sygna Bridge central server.\n\n### Get VASP Information\n\n```python\n# Get List of VASPs associated with public keys.\nverify = True # set verify to true to verify the signature attached with api response automatically.\nvasps = sb_api_instance.get_vasp_list(verify)\n\n# Or call use get_vasp_public_key() to directly get public key for a specific VASP.\npublic_key = sb_api_instance.get_vasp_public_key(\"10298\", verify)\n```\n\n### For Originator\n\nThere are two API calls from **transaction originator** to Sygna Bridge Server defined in the protocol, which are `post_permission_request` and `post_transaction_id`. \n\nThe full logic of originator would be like the following:\n\n```python\n# originator.py\nrecipient_public_key = sb_api_instance.get_vasp_public_key(\"10298\")\nprivate_info = sygna_bridge_util.crypto.sygna_encrypt_private_data(\n # example from above\n sensitive_data, \n recipient_public_key\n)\n\ndata_dt = \"2019-07-29T07:29:80Z\"\n\ndata_to_sign = {\n \"private_info\":private_info,\n # from example above\n \"transaction\":transaction,\n \"data_dt\":data_dt\n}\n\ntransfer_data = sygna_bridge_util.crypto.sign_permission_request(\n data_to_sign, \n sender_privKey\n)\n\ncallback_url = \"https://81f7d956.ngrok.io/v2/originator/transaction/premission\"\ncallback_data = sygna_bridge_util.crypto.sign_callback(\n {\n \"callback_url\":callback_url\n }, \n sender_privKey\n)\n\nresponse = sb_api_instance.post_permission_request(\n {\n \"data\":transfer_data,\n \"callback\":callback_data\n }\n)\n\n# Broadcast your transaction to blockchain after got and api response at your api server.\ntxid = \"1a0c9bef489a136f7e05671f7f7fada2b9d96ac9f44598e1bcaa4779ac564dcd\"\n\n# Inform Sygna Bridge that a specific transfer is successfully broadcasted to the blockchain.\n\nsend_tx_id_data = sygna_bridge_util.crypto.sign_transaction_id(\n {\n \"transfer_id\":response[\"transfer_id\"], \n \"txid\":txid\n }, \n sender_privKey\n)\npost_tx_id_response = sb_api_instance.post_transaction_id(send_tx_id_data)\n\n```\n\n### For Beneficiary\n\nThere is only one api for Beneficiary VASP to call, which is `post_permission`. After the beneficiary server confirm their legitimacy of a transfer request, they will sign `{ transfer_id, permission_status }` using `sign_permission()` function, and send the result with signature to Sygna Bridge Central Server.\n\n```Python\n\npermission_status = \"ACCEPTED\" # or \"REJECTED\"\npermission_data = sygna_bridge_util.crypto.sign_permission(\n {\n \"transfer_id\":response[\"transfer_id\"], \n \"permission_status\":permission_status\n }, \n beneficiary_private_key\n)\nfinal_result = sb_api_instance.post_permission(permission_data)\n```\n\nFor more complete example, please refer to [Example](example/main.py) file.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This is a Python library to help you build servers/services within Sygna Bridge Ecosystem.",
"version": "2.0.3",
"project_urls": {
"Homepage": "https://github.com/CoolBitX-Technology/sygna-bridge-util-py"
},
"split_keywords": [
"sygna-bridge-util",
"sygna",
"bridge",
"sygna-bridge",
"ecosystem"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "45961b7d404b27b9097bcae44dcbbe0cb11d818e31c1311ef2ed16cb2686d53f",
"md5": "fff860d0343d361d91029f363519287f",
"sha256": "66dfdc8027fc0517abfc07a54cce98ec2180f06614f78861e72804b02ef6dbee"
},
"downloads": -1,
"filename": "sygna_bridge_util-2.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fff860d0343d361d91029f363519287f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 13797,
"upload_time": "2023-11-17T03:34:01",
"upload_time_iso_8601": "2023-11-17T03:34:01.129437Z",
"url": "https://files.pythonhosted.org/packages/45/96/1b7d404b27b9097bcae44dcbbe0cb11d818e31c1311ef2ed16cb2686d53f/sygna_bridge_util-2.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "034817e9a17a6f241afc1b5d124baebb69a1d72c2d26b0dd1879a684b5d89283",
"md5": "0667acf1a398f1ae70f2bd5ba4bf20bf",
"sha256": "0d68df1f7ec97067648b0219020637dc7b50f21a94f594cd87c8c9c5f572d946"
},
"downloads": -1,
"filename": "sygna-bridge-util-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "0667acf1a398f1ae70f2bd5ba4bf20bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 13257,
"upload_time": "2023-11-17T03:34:02",
"upload_time_iso_8601": "2023-11-17T03:34:02.729946Z",
"url": "https://files.pythonhosted.org/packages/03/48/17e9a17a6f241afc1b5d124baebb69a1d72c2d26b0dd1879a684b5d89283/sygna-bridge-util-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-17 03:34:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CoolBitX-Technology",
"github_project": "sygna-bridge-util-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "sygna-bridge-util"
}
JSON
