From e4fa72d128de20c1cd596f81b56324d7ceef501c Mon Sep 17 00:00:00 2001 From: charlieflipside <107061601+charlieflipside@users.noreply.github.com> Date: Tue, 30 Aug 2022 10:46:26 -0400 Subject: [PATCH] update-README --- README.md | 133 ++++++++++++++++++++- man/address_net_on_chain.Rd | 5 +- man/address_time_weighted_token_balance.Rd | 10 +- man/address_token_accumulate.Rd | 9 +- man/address_token_balance.Rd | 10 +- man/address_transfer_volume.Rd | 5 +- renv.lock | 4 +- 7 files changed, 160 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 100b938..da014c8 100644 --- a/README.md +++ b/README.md @@ -1 +1,132 @@ -README \ No newline at end of file +# ETHSCORE + +ETHSCORE is a framework for identifying addresses and scoring their behavior. With the vision of simplifying the development of web3 'reputation'. Initially started with 5 fully on-chain metrics, new metrics will be added over-time including off-chain metrics, e.g., Snapshot governance voting. + +Use cases such as under-collateralized credit or 'social' scoring may fall under this framework, but that is not the direct intention. ethscore was originally developed to assist in airdrop design so new protocols could more easily identify users for their applications that have a history of using similar apps and bribe them with tokens/ownership in the protocol as a direct to customer: Customer Acquisition Cost. + +## Available Metrics + +Note: all documentation available within the ethscore package, e.g., `?ethscore::address_token_balance` + +All functions leverage Flipside Crypto's free [shroomDK API](https://sdk.flipsidecrypto.xyz/shroomdk) and require a shroomDK API Key and the [shroomDK R package](https://github.com/FlipsideCrypto/sdk/tree/main/r/shroomDK). ShroomDK returns a maximum of 1,000,000 rows of data. Vary your block_min and block_max accordingly to stitch together large data if desired, or use min_tokens to remove more dust accounts. + +### address_token_balance() + +Token balance of an address at a specific block height. Example: Alice held 20 UNI at block 15,000,000. + +Arguments include: + +- token_address: ERC20 token contract address to assess balance +- min_tokens: Minimum amount of tokens acknowledged. Already decimal adjusted, useful for ignoring dust balances. +- block_max: The block height to assess balance at. +- api_key: Flipside Crypto ShroomDK API Key to create and access SQL queries. + +Example: + + UNI_atb <- address_token_balance( + token_address = tolower("0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984"), #UNI token + min_tokens = 0.01, + block_max = 15000000, + api_key = readLines("api_key.txt") # always gitignore your API keys! + ) + +Returns a data frame of the following: + +- BLOCK: Block where user last changed their balance (i.e., traded or transferred) +- TOKEN_ADDRESS: ERC20 address provided +- ADDRESS: The EOA or contract that holds the balance +- OLD_VALUE: Amount of token before latest trade or transfer +- NEW_VALUE Amount of token as of BLOCK, i.e. balance after their latest trade or transfer +- ADDRESS_TYPE: If ADDRESS is known to be 'contract address' or 'gnosis safe address'. If neither it is assumed to be an 'EOA'. Some EOAs may have a balance but have never initiated a transaction. These are noted as 'EOA-0tx' Note: contracts, including gnosis safes may not have consistent owners across different EVM chains. + +### address_time_weighted_token_balance() + +Time weighted token balance of an address between 2 block heights. Holding 20 UNI for 10,000 blocks might be more interesting to score than someone buying 20 UNI right before a snapshot for an airdrop. + +Arguments include: + +- token_address: ERC20 token contract address to assess balance +- min_tokens: Minimum amount of tokens acknowledged. Already decimal adjusted, useful for ignoring dust balances. +- block_min: Initial block to start scoring balances over time, default 0 (genesis block). +- block_max: The block height to assess balance at. +- amount_weighting: Weight by amounts held across time, default TRUE. If FALSE, it treats all amounts as binary. Person had at least min_tokens at a block or they did not. To NOT weight by time, use `address_token_balance()` instead of this function. +- api_key: Flipside Crypto ShroomDK API Key to create and access SQL queries. + +Example: + + address_time_weighted_token_balance( + token_address = tolower("0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984"), #UNI token + min_tokens = 0.01, + block_min = 10000000, + block_max = 15000000, + amount_weighting = TRUE, + api_key = readLines("api_key.txt") + ) + +Returns a data frame of the following: + +- ADDRESS: The EOA or contract that holds the balance +- TOKEN_ADDRESS: ERC20 address provided +- time_weighted_score: 1 point per 1 token held per 1,000 blocks. If amount_weighting = FALSE, 1 point per 1,000 blocks where balance was at least min_tokens. +- ADDRESS_TYPE: If ADDRESS is known to be 'contract address' or 'gnosis safe address'. If neither it is assumed to be an 'EOA'. Some EOAs may have a balance but have never initiated a transaction. These are noted as 'EOA-0tx' Note: contracts, including gnosis safes may not have consistent owners across different EVM chains. + +### address_transfer_volume() + +Total transfer volume of a token between two block heights. Ignores direction of transfer. Alice traded and/or transferred a total of 2,000 UNI between blocks 10,000,000 and 15,000,000. + +Arguments include: + +- token_address: ERC20 token contract address to assess balance +- min_tokens: Minimum amount of tokens acknowledged. Already decimal adjusted, useful for ignoring dust balances. +- block_min: Initial block to start scoring balances over time, default 0 (genesis block). +- block_max: The block height to assess balance at. +- api_key: Flipside Crypto ShroomDK API Key to create and access SQL queries. + +Example: + + address_transfer_volume( + token_address = tolower("0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984"), #UNI token + block_min = 10000000, + block_max = 15000000, + min_tokens = 10, + api_key = readLines("api_key.txt") + ) + +Returns a data frame of the following: + +- ADDRESS: The EOA or contract that holds the balance +- TOKEN_ADDRESS: ERC20 address provided +- VOLUME: amount of tokens transferred/traded between block_min and block_max. +- ADDRESS_TYPE: If ADDRESS is known to be 'contract address' or 'gnosis safe address'. If neither it is assumed to be an 'EOA'. Some EOAs may have a balance but have never initiated a transaction. These are noted as 'EOA-0tx' Note: contracts, including gnosis safes may not have consistent owners across different EVM chains. + +### address_token_accumulate() + +Net accumulation of a token between two block heights. By default excludes net sellers. Alice net gained 200 UNI between blocks 10,000,000 and 15,000,000. + +Arguments include: + +- token_address: ERC20 token contract address to assess balance +- min_tokens: Minimum amount of tokens acknowledged. Already decimal adjusted, useful for ignoring dust balances. Default 0.01. Use -Inf to include net sellers (but note: API max is 1M rows). +- block_min: Initial block to start scoring balances over time, default 0 (genesis block). +- block_max: The block height to assess balance at. +- api_key: Flipside Crypto ShroomDK API Key to create and access SQL queries. + +Example: + +``` +address_token_accumulate( +token_address = tolower("0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984"), #UNI token + block_min = 10000000, + block_max = 15000000, + min_tokens = 1, + api_key = readLines("api_key.txt") +) +``` + +Returns a data frame of the following: + +- ADDRESS: The EOA or contract that holds the balance +- TOKEN_ADDRESS: ERC20 address provided +- NET_CHANGE: net amount of tokens accumulated between block_min and block_max +- ADDRESS_TYPE: If ADDRESS is known to be 'contract address' or 'gnosis safe address'. If neither it is assumed to be an 'EOA'. Some EOAs may have a balance but have never initiated a transaction. These are noted as 'EOA-0tx' Note: contracts, including gnosis safes may not have consistent owners across different EVM chains. + diff --git a/man/address_net_on_chain.Rd b/man/address_net_on_chain.Rd index ae717c9..0a7b35b 100644 --- a/man/address_net_on_chain.Rd +++ b/man/address_net_on_chain.Rd @@ -22,7 +22,7 @@ address_net_on_chain( \item{decimal_reduction}{Most ERC20 have 18 decimals, but stablecoins often have only 6.} -\item{min_tokens}{Minimum amount of tokens acknowledged. Already decimal adjusted, useful to +\item{min_tokens}{Minimum amount of tokens acknowledged. Already decimal adjusted, useful for ignoring dust balances. Default 0.0001. Use -Inf to include net sellers (but note: API max is 1M rows.).} \item{api_key}{Flipside Crypto ShroomDK API Key to create and access SQL queries.} @@ -33,6 +33,9 @@ A data frame of the form:\tabular{lc}{ ADDRESS \tab The EOA or contract that holds the balance \cr TOKEN_ADDRESS \tab ERC20 address provided \cr NET_ONTO_CHAIN \tab net amount of token taken from central exchanges between block_min and block_max \cr + ADDRESS_TYPE \tab If ADDRESS is known to be 'contract address' or 'gnosis safe address'. \cr + If neither it is assumed to be an 'EOA'. Some EOAs may have a balance but have never initiated a transaction \tab \cr + These are noted as 'EOA-0tx' Note: contracts, including gnosis safes may not have consistent owners across different EVM chains. \tab \cr } } \description{ diff --git a/man/address_time_weighted_token_balance.Rd b/man/address_time_weighted_token_balance.Rd index 7cf8889..59f0f61 100644 --- a/man/address_time_weighted_token_balance.Rd +++ b/man/address_time_weighted_token_balance.Rd @@ -6,7 +6,7 @@ \usage{ address_time_weighted_token_balance( token_address, - min_tokens = 0.0001, + min_tokens = 1e-04, block_min = 0, block_max, amount_weighting = TRUE, @@ -16,7 +16,7 @@ address_time_weighted_token_balance( \arguments{ \item{token_address}{ERC20 token contract address to assess balance.} -\item{min_tokens}{Minimum amount of tokens acknowledged. Already decimal adjusted, useful to +\item{min_tokens}{Minimum amount of tokens acknowledged. Already decimal adjusted, useful for ignoring dust balances.} \item{block_min}{Initial block to start scoring balances over time, default 0 (genesis block).} @@ -34,8 +34,10 @@ A data frame of the form:\tabular{lc}{ \tab \cr ADDRESS \tab The EOA or contract that holds the balance \cr TOKEN_ADDRESS \tab ERC20 address provided \cr - time_weighted_score \tab 1 point per 1 token held per 1,000 blocks (amount_weighting = FALSE is \cr - 1 point per 1000 blocks where balance was above min_tokens) \tab \cr + time_weighted_score \tab 1 point per 1 token held per 1,000 blocks (amount_weighting = FALSE is 1 point per 1000 blocks where balance was above min_tokens) \cr + ADDRESS_TYPE \tab If ADDRESS is known to be 'contract address' or 'gnosis safe address'. \cr + If neither it is assumed to be an 'EOA'. Some EOAs may have a balance but have never initiated a transaction \tab \cr + These are noted as 'EOA-0tx' Note: contracts, including gnosis safes may not have consistent owners across different EVM chains. \tab \cr } } \description{ diff --git a/man/address_token_accumulate.Rd b/man/address_token_accumulate.Rd index 67a2d04..fa26b1f 100644 --- a/man/address_token_accumulate.Rd +++ b/man/address_token_accumulate.Rd @@ -8,7 +8,7 @@ address_token_accumulate( token_address, block_min = 0, block_max, - min_tokens = 0.0001, + min_tokens = 0.01, api_key ) } @@ -19,8 +19,8 @@ address_token_accumulate( \item{block_max}{The block height to assess balance at (for reproducibility).} -\item{min_tokens}{Minimum amount of tokens acknowledged. Already decimal adjusted, useful to -ignoring dust balances. Default 0.0001. Use -Inf to include net sellers (but note: API max is 1M rows.).} +\item{min_tokens}{Minimum amount of tokens acknowledged. Already decimal adjusted, useful for +ignoring dust balances. Default 0.01. Use -Inf to include net sellers (but note: API max is 1M rows.).} \item{api_key}{Flipside Crypto ShroomDK API Key to create and access SQL queries.} } @@ -30,6 +30,9 @@ A data frame of the form:\tabular{lc}{ ADDRESS \tab The EOA or contract that holds the balance \cr TOKEN_ADDRESS \tab ERC20 address provided \cr NET_CHANGE \tab net amount of tokens accumulated between block_min and block_max \cr + ADDRESS_TYPE \tab If ADDRESS is known to be 'contract address' or 'gnosis safe address'. \cr + If neither it is assumed to be an 'EOA'. Some EOAs may have a balance but have never initiated a transaction \tab \cr + These are noted as 'EOA-0tx' Note: contracts, including gnosis safes may not have consistent owners across different EVM chains. \tab \cr } } \description{ diff --git a/man/address_token_balance.Rd b/man/address_token_balance.Rd index be229df..7c2aed5 100644 --- a/man/address_token_balance.Rd +++ b/man/address_token_balance.Rd @@ -6,7 +6,7 @@ \usage{ address_token_balance( token_address, - min_tokens = 0.0001, + min_tokens = 1e-04, block_max, api_key = api_key ) @@ -14,7 +14,7 @@ address_token_balance( \arguments{ \item{token_address}{ERC20 token contract address to assess balance} -\item{min_tokens}{Minimum amount of tokens acknowledged. Already decimal adjusted, useful to +\item{min_tokens}{Minimum amount of tokens acknowledged. Already decimal adjusted, useful for ignoring dust balances.} \item{block_max}{The block height to assess balance at (for reproducibility)} @@ -25,12 +25,13 @@ ignoring dust balances.} Data frame of form:\tabular{lc}{ \tab \cr BLOCK \tab Block where user last changed their balance (traded or transferred) \cr - HASH \tab Tx hash where user last traded or transferred \cr TOKEN_ADDRESS \tab ERC20 address provided \cr ADDRESS \tab The EOA or contract that holds the balance \cr - SYMBOL \tab ERC20 symbol, e.g., "UNI" \cr OLD_VALUE \tab Amount of token before latest trade or transfer \cr NEW_VALUE \tab Amount of token as of BLOCK, i.e. balance after their latest trade or transfer \cr + ADDRESS_TYPE \tab If ADDRESS is known to be 'contract address' or 'gnosis safe address'. \cr + If neither it is assumed to be an 'EOA'. Some EOAs may have a balance but have never initiated a transaction \tab \cr + These are noted as 'EOA-0tx' Note: contracts, including gnosis safes may not have consistent owners across different EVM chains. \tab \cr } } \description{ @@ -46,4 +47,5 @@ token_address = tolower("0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984"), #UNI toke api_key = readLines("api_key.txt") ) } + } diff --git a/man/address_transfer_volume.Rd b/man/address_transfer_volume.Rd index 181c7a4..a5db840 100644 --- a/man/address_transfer_volume.Rd +++ b/man/address_transfer_volume.Rd @@ -19,7 +19,7 @@ address_transfer_volume( \item{block_max}{The block height to assess balance at (for reproducibility).} -\item{min_tokens}{Minimum amount of tokens acknowledged. Already decimal adjusted, useful to +\item{min_tokens}{Minimum amount of tokens acknowledged. Already decimal adjusted, useful for ignoring dust balances. Default 1.} \item{api_key}{Flipside Crypto ShroomDK API Key to create and access SQL queries.} @@ -30,6 +30,9 @@ A data frame of the form:\tabular{lc}{ ADDRESS \tab The EOA or contract with the volume \cr TOKEN_ADDRESS \tab ERC20 address provided \cr VOLUME \tab amount of tokens transferred/traded between block_min and block_max \cr + ADDRESS_TYPE \tab If ADDRESS is known to be 'contract address' or 'gnosis safe address'. \cr + If neither it is assumed to be an 'EOA'. Some EOAs may have a balance but have never initiated a transaction \tab \cr + These are noted as 'EOA-0tx' Note: contracts, including gnosis safes may not have consistent owners across different EVM chains. \tab \cr } } \description{ diff --git a/renv.lock b/renv.lock index 812f202..3e62bed 100644 --- a/renv.lock +++ b/renv.lock @@ -37,10 +37,10 @@ }, "httr": { "Package": "httr", - "Version": "1.4.3", + "Version": "1.4.4", "Source": "Repository", "Repository": "CRAN", - "Hash": "88d1b310583777edf01ccd1216fb0b2b", + "Hash": "57557fac46471f0dbbf44705cc6a5c8c", "Requirements": [ "R6", "curl",