| Name | sybil-scorer JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | |
| Summary | A sybil scoring tool |
| upload_time | 2023-11-05 16:01:13 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | MIT License Copyright (c) 2023 Poupou Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
sybil
oss
gitcoin
quadratic
opendata community
odc
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sybil-scorer
Sybil scorer is a python package that provides useful classes and methods to analyze the behavior of addresses.
## Help Out
Consider donating on Gitcoin [https://explorer.gitcoin.co/#/round/10/0x8de918f0163b2021839a8d84954dd7e8e151326d/0x8de918f0163b2021839a8d84954dd7e8e151326d-66](https://explorer.gitcoin.co/#/round/10/0x8de918f0163b2021839a8d84954dd7e8e151326d/0x8de918f0163b2021839a8d84954dd7e8e151326d-66)
## Installation
- Python >= 3.9
- ```pip install sybil-scorer```
## What is inside?
The package has two main sub-packages.
- **sbdata** is a package to easily retrieve a large amount of data from the Flipside API.
- **sblegos** a package to perform on-chain transactions analysis to detect potential Sybil behavior.
- **sbutils** is a package that makes it easy to load the data extracted with sbdata and use it in sblegos.
More details on the packages and examples are provided below.
### sbdata
An example script to retrieve data from the flipside API is provided in the script folder:
script/demo_extract_eth_txs_oss.py
It could also be used to retrieve transactional data from an address with some simple calls:
``` python
import os
from sbdata.FlipsideApi import FlipsideApi
api_key = os.environ['FLIPSIDE_API_KEY']
flipside_api = FlipsideApi(api_key, max_address=1000)
address = ['0x06cd8288dc001024ce0a1cf39caaedc0e2db9c82']
tx_add_eth = flipside_api.get_transactions(address, chain='ethereum')
```
It walks you through the process of retrieving data from the flipside API and saving it in a folder.
To use this package you will need an API key from flipside that you can get
here: https://sdk.flipsidecrypto.xyz/shroomdk/apikeys
Useful example script are provided in the script folder.
### sblegos and sbutils
sblegos provides the following analysis of legos:
- **has_same_seed** : true if the address has the same seed as any other address in the grants contributors
- **has_same_seed_naive** : true if the address has the same seed as any other address in the grants contributors with a
naive approach: address of the from_address of the first transaction.
- **has_suspicious_seed_behavior** : true if has_same_seed is different from has_same_seed_naive. It means the user
performed some actions before funding his wallet.
- **has_interacted_with_other_contributor** : true if the user has interacted with any other contributor to the grant
- **has_less_than_n_transactions** : true if the user has less than n transactions.
- **has_transaction_similitude** : true if the user has a transaction history that is similar to any other contributor
to the grant.
- **has_transaction_similitude_opti** : an optimized version of has_transaction_similitude, when used across multiple
addresses.
A jupyter notebook using both packages is available as a jupyter notebook
here https://github.com/poupou-web3/grant-exploration/blob/main/gr-climate-exploration.ipynb
The following snippet of code will check if any address has the same seed as any other contributor to the climate grant
``` python
import os
from pathlib import Path
import numpy as np
import pandas as pd
from sbutils import LoadData
from sblegos.TransactionAnalyser import TransactionAnalyser as txa
# Set path to data folder
PATH_TO_EXPORT = 'path to where the data was extracted'
CHAIN = 'the name of the chain you want to analyse for example "ethereum"'
# Load the votes data
array_unique_address = df_votes['voter'].unique() # array of unique voters, here df_votes contains all the votes made on a grant
# Be sure that the address are in lower case
array_unique_address = np.char.lower(array_unique_address.astype(str))
print(f'Number of unique voter: {len(array_unique_address)}')
# Load the transactions of the addresses using the sbutils package
data_loader = LoadData.LoadData(PATH_TO_EXPORT)
df_tx = data_loader.create_df_tx(CHAIN, array_unique_address)
# Initialise the TransactionAnalyser class
tx_analyser = txa(df_tx, array_address=array_unique_address)
# Compute some predetermined features, it can takes some time especially on large datasets
df_matching_address = tx_analyser.get_df_features()
df_matching_address.head(2)
# For individual computation of the features:
df_matching_address = pd.DataFrame(array_unique_address, columns=["address"])
df_matching_address['seed_same_naive'] = df_matching_address.loc[:, 'address'].apply(lambda x : tx_analyser.has_same_seed_naive(x))
```
## Documentation
The documentation of the package is available at https://sybil-scorer.readthedocs.io/en/latest/py-modindex.html.
For a local version of the documentation, you can build it using sphinx. with the following commands:
```
cd docs
sphinx-apidoc -o ./source ../sbscorer
make html
```
Then open the file docs/build/html/index.html in your browser.
The local version of the documentation is prettier than the one hosted on readthedocs.
## Example Data
Some data for easier use of the package in the context of Gitcoin grants are made available on Ocean market.
### Gitcoin Citizen Round data
#### Transaction data
You can load the data directly into the `df_tx` variable.
https://huggingface.co/datasets/Poupou/Gitcoin-Citizen-Round/blob/main/tx_citizen_round.parquet
These are all the transactions performed by users who contributed to the Citizen round on grant as of 30th of June 2023.
#### Example of vote data
Example query to extract the vote data of the citizen round of June 2023 from the Flipside API:
https://flipsidecrypto.xyz/poupou/q/j3E9SEfMLkxG/citizen-round-votes
You could also use the data available on hugging face:
https://huggingface.co/datasets/Poupou/Gitcoin-Citizen-Round/blob/main/citizen-votes.csv
## Future works
Future works include:
- Adding more transactional analysis lego.
- Adding temporal features to a clustering algorithm as researched in the first
hackathon [submission](https://github.com/poupou-web3/GC-ODS-Sybil).
- Improving seed legos to output cluster of addresses instead of a boolean.
- See issues at www.github.com/poupou-web3/sybil-scorer/issues
Raw data
{
"_id": null,
"home_page": "",
"name": "sybil-scorer",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "Sybil,OSS,Gitcoin,Quadratic,OpenData Community,ODC",
"author": "",
"author_email": "Poupou <poupou-web3@protonmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b2/eb/645d2db1508d565f430b4f226c46bda52cfeb2d1d7c04f95522252f78958/sybil-scorer-0.4.0.tar.gz",
"platform": null,
"description": "# sybil-scorer\r\n\r\nSybil scorer is a python package that provides useful classes and methods to analyze the behavior of addresses.\r\n\r\n## Help Out\r\nConsider donating on Gitcoin [https://explorer.gitcoin.co/#/round/10/0x8de918f0163b2021839a8d84954dd7e8e151326d/0x8de918f0163b2021839a8d84954dd7e8e151326d-66](https://explorer.gitcoin.co/#/round/10/0x8de918f0163b2021839a8d84954dd7e8e151326d/0x8de918f0163b2021839a8d84954dd7e8e151326d-66)\r\n\r\n## Installation\r\n\r\n- Python >= 3.9\r\n- ```pip install sybil-scorer```\r\n\r\n## What is inside?\r\n\r\nThe package has two main sub-packages.\r\n\r\n- **sbdata** is a package to easily retrieve a large amount of data from the Flipside API.\r\n- **sblegos** a package to perform on-chain transactions analysis to detect potential Sybil behavior.\r\n- **sbutils** is a package that makes it easy to load the data extracted with sbdata and use it in sblegos.\r\n\r\nMore details on the packages and examples are provided below.\r\n\r\n### sbdata\r\n\r\nAn example script to retrieve data from the flipside API is provided in the script folder:\r\nscript/demo_extract_eth_txs_oss.py\r\n\r\nIt could also be used to retrieve transactional data from an address with some simple calls:\r\n\r\n``` python\r\nimport os\r\nfrom sbdata.FlipsideApi import FlipsideApi\r\n\r\napi_key = os.environ['FLIPSIDE_API_KEY']\r\nflipside_api = FlipsideApi(api_key, max_address=1000)\r\naddress = ['0x06cd8288dc001024ce0a1cf39caaedc0e2db9c82']\r\ntx_add_eth = flipside_api.get_transactions(address, chain='ethereum')\r\n```\r\n\r\nIt walks you through the process of retrieving data from the flipside API and saving it in a folder.\r\n\r\nTo use this package you will need an API key from flipside that you can get\r\nhere: https://sdk.flipsidecrypto.xyz/shroomdk/apikeys\r\n\r\nUseful example script are provided in the script folder.\r\n\r\n### sblegos and sbutils\r\n\r\nsblegos provides the following analysis of legos:\r\n\r\n- **has_same_seed** : true if the address has the same seed as any other address in the grants contributors\r\n- **has_same_seed_naive** : true if the address has the same seed as any other address in the grants contributors with a\r\n naive approach: address of the from_address of the first transaction.\r\n- **has_suspicious_seed_behavior** : true if has_same_seed is different from has_same_seed_naive. It means the user\r\n performed some actions before funding his wallet.\r\n- **has_interacted_with_other_contributor** : true if the user has interacted with any other contributor to the grant\r\n- **has_less_than_n_transactions** : true if the user has less than n transactions.\r\n- **has_transaction_similitude** : true if the user has a transaction history that is similar to any other contributor\r\n to the grant.\r\n- **has_transaction_similitude_opti** : an optimized version of has_transaction_similitude, when used across multiple\r\n addresses.\r\n\r\nA jupyter notebook using both packages is available as a jupyter notebook\r\nhere https://github.com/poupou-web3/grant-exploration/blob/main/gr-climate-exploration.ipynb\r\n\r\nThe following snippet of code will check if any address has the same seed as any other contributor to the climate grant\r\n\r\n``` python\r\nimport os\r\nfrom pathlib import Path\r\nimport numpy as np\r\nimport pandas as pd\r\nfrom sbutils import LoadData\r\nfrom sblegos.TransactionAnalyser import TransactionAnalyser as txa\r\n\r\n# Set path to data folder\r\nPATH_TO_EXPORT = 'path to where the data was extracted'\r\nCHAIN = 'the name of the chain you want to analyse for example \"ethereum\"'\r\n\r\n# Load the votes data\r\narray_unique_address = df_votes['voter'].unique() # array of unique voters, here df_votes contains all the votes made on a grant \r\n\r\n# Be sure that the address are in lower case\r\narray_unique_address = np.char.lower(array_unique_address.astype(str))\r\nprint(f'Number of unique voter: {len(array_unique_address)}')\r\n\r\n# Load the transactions of the addresses using the sbutils package\r\ndata_loader = LoadData.LoadData(PATH_TO_EXPORT)\r\ndf_tx = data_loader.create_df_tx(CHAIN, array_unique_address)\r\n\r\n# Initialise the TransactionAnalyser class\r\ntx_analyser = txa(df_tx, array_address=array_unique_address)\r\n\r\n# Compute some predetermined features, it can takes some time especially on large datasets\r\ndf_matching_address = tx_analyser.get_df_features()\r\ndf_matching_address.head(2)\r\n\r\n# For individual computation of the features:\r\ndf_matching_address = pd.DataFrame(array_unique_address, columns=[\"address\"])\r\ndf_matching_address['seed_same_naive'] = df_matching_address.loc[:, 'address'].apply(lambda x : tx_analyser.has_same_seed_naive(x))\r\n\r\n```\r\n\r\n## Documentation\r\n\r\nThe documentation of the package is available at https://sybil-scorer.readthedocs.io/en/latest/py-modindex.html.\r\nFor a local version of the documentation, you can build it using sphinx. with the following commands:\r\n\r\n```\r\ncd docs\r\nsphinx-apidoc -o ./source ../sbscorer\r\nmake html\r\n```\r\n\r\nThen open the file docs/build/html/index.html in your browser.\r\nThe local version of the documentation is prettier than the one hosted on readthedocs.\r\n\r\n\r\n## Example Data\r\n\r\nSome data for easier use of the package in the context of Gitcoin grants are made available on Ocean market.\r\n\r\n### Gitcoin Citizen Round data\r\n\r\n#### Transaction data\r\n\r\nYou can load the data directly into the `df_tx` variable.\r\nhttps://huggingface.co/datasets/Poupou/Gitcoin-Citizen-Round/blob/main/tx_citizen_round.parquet\r\n\r\nThese are all the transactions performed by users who contributed to the Citizen round on grant as of 30th of June 2023.\r\n\r\n#### Example of vote data\r\n\r\nExample query to extract the vote data of the citizen round of June 2023 from the Flipside API:\r\nhttps://flipsidecrypto.xyz/poupou/q/j3E9SEfMLkxG/citizen-round-votes\r\n\r\nYou could also use the data available on hugging face:\r\nhttps://huggingface.co/datasets/Poupou/Gitcoin-Citizen-Round/blob/main/citizen-votes.csv\r\n\r\n## Future works\r\n\r\nFuture works include:\r\n\r\n- Adding more transactional analysis lego.\r\n- Adding temporal features to a clustering algorithm as researched in the first\r\n hackathon [submission](https://github.com/poupou-web3/GC-ODS-Sybil).\r\n- Improving seed legos to output cluster of addresses instead of a boolean.\r\n- See issues at www.github.com/poupou-web3/sybil-scorer/issues\r\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Poupou Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "A sybil scoring tool",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://sybil-scorer.readthedocs.io/en/latest/py-modindex.html",
"Homepage": "https://github.com/poupou-web3/sybil-scorer"
},
"split_keywords": [
"sybil",
"oss",
"gitcoin",
"quadratic",
"opendata community",
"odc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "87074034538f88d1d4663be3f7c99dbc9010dda39b7b8d8f41d78d5bcca93d54",
"md5": "552e2a1a2a39763ee170af10560fcc98",
"sha256": "83690fb2d1c9f48e7ef7f57411743f57cc23517425f318fb9bd5f5b198b9df82"
},
"downloads": -1,
"filename": "sybil_scorer-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "552e2a1a2a39763ee170af10560fcc98",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 24843,
"upload_time": "2023-11-05T16:01:11",
"upload_time_iso_8601": "2023-11-05T16:01:11.727343Z",
"url": "https://files.pythonhosted.org/packages/87/07/4034538f88d1d4663be3f7c99dbc9010dda39b7b8d8f41d78d5bcca93d54/sybil_scorer-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b2eb645d2db1508d565f430b4f226c46bda52cfeb2d1d7c04f95522252f78958",
"md5": "79c7609f05e2a128eb6b12f16f8218ec",
"sha256": "83b2ecfef844e7ef89e44bfa23739d67ab5bf8d622719393bdd4706c36cd34b3"
},
"downloads": -1,
"filename": "sybil-scorer-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "79c7609f05e2a128eb6b12f16f8218ec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 23524,
"upload_time": "2023-11-05T16:01:13",
"upload_time_iso_8601": "2023-11-05T16:01:13.515526Z",
"url": "https://files.pythonhosted.org/packages/b2/eb/645d2db1508d565f430b4f226c46bda52cfeb2d1d7c04f95522252f78958/sybil-scorer-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-05 16:01:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "poupou-web3",
"github_project": "sybil-scorer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "sybil-scorer"
}
