{"id":22302973,"url":"https://github.com/xrplwin/unlreportreader","last_synced_at":"2025-03-26T00:32:10.799Z","repository":{"id":197289587,"uuid":"697633976","full_name":"XRPLWin/UNLReportReader","owner":"XRPLWin","description":"Fetches and parses UNLReports on Xahau network.","archived":false,"fork":false,"pushed_at":"2023-11-07T18:54:09.000Z","size":39,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-04T21:03:04.119Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XRPLWin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["zgrguric"]}},"created_at":"2023-09-28T06:48:28.000Z","updated_at":"2023-09-30T18:19:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"92392c7b-6add-4d18-a364-423823dec14c","html_url":"https://github.com/XRPLWin/UNLReportReader","commit_stats":null,"previous_names":["xrplwin/unlreportparser","xrplwin/unlreportreader"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XRPLWin%2FUNLReportReader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XRPLWin%2FUNLReportReader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XRPLWin%2FUNLReportReader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XRPLWin%2FUNLReportReader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XRPLWin","download_url":"https://codeload.github.com/XRPLWin/UNLReportReader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245566098,"owners_count":20636390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T18:42:08.052Z","updated_at":"2025-03-26T00:32:10.761Z","avatar_url":"https://github.com/XRPLWin.png","language":"PHP","funding_links":["https://github.com/sponsors/zgrguric"],"categories":[],"sub_categories":[],"readme":"![main workflow](https://github.com/XRPLWin/UNLReportReader/actions/workflows/main.yml/badge.svg)\n[![GitHub license](https://img.shields.io/github/license/XRPLWin/UNLReportReader)](https://github.com/XRPLWin/UNLReportReader/blob/main/LICENSE)\n[![Total Downloads](https://img.shields.io/packagist/dt/xrplwin/unlreportreader.svg?style=flat)](https://packagist.org/packages/xrplwin/unlreportreader)\n\n# UNLReport Reader\n\nFetches UNLReports on Xahau network.\n\nThis is PHP package where you can provide flag ledger and script will parse and return final validator report. For requested ledger_index script will return final UNLReport state for that ledger_index.\n\n## Requirements\n- PHP 8.1 or higher\n- [Composer](https://getcomposer.org/)\n\n## Installation\n```\ncomposer require xrplwin/unlreportreader\n```\n\n## Ranges\nWhen fetching ledger index report data, each ledger index % 256 is flag ledger. **At flag ledger UNLReport is still not applied**, UNLReport is applied from next ledger (next 256 ledgers including last flag ledger). See table below to understand ranges when querying specific ledger index.\n\n| Viewing ledger_index | Applied from | Applied to |\n|-|-|-|\n| ... | ... | ... |\n| 256 (flag) | 1 | 256 |\n| ... | ... | ... |\n| 510 (flag-2) | 257 | 512 |\n| 511 (flag-1) | 257 | 512 |\n| 512 (flag) | 257 | 512 |\n| 513 (flag+1) | 513 | 768 |\n| 514 (flag+2) | 513 | 768 |\n| ... | ... | ... |\n\n## Usage sample\n\n```PHP\nuse XRPLWin\\UNLReportReader\\UNLReportReader;\n\n$reader = new UNLReportReader('https://xahau-test.net');\n\n$response = $reader-\u003efetchSingle(6873344); //?array\n/*\narray [\n    \"flag_ledger_index\" =\u003e 6873344\n    \"flag_ledger_close_time\" =\u003e 748969761\n    \"report_range\" =\u003e [6873089,6873344]\n    \"import_vlkey\" =\u003e \"E1...\"\n    \"active_validators\" =\u003e array [\n        0 =\u003e array:2 [\n            \"?Account\" =\u003e \"r2...\"\n            \"PublicKey\" =\u003e \"E2...\"\n        ]\n        1 =\u003e array:2 [\n            \"?Account\" =\u003e \"r3...\"\n            \"PublicKey\" =\u003e \"E3...\"\n        ], ...\n    ]\n]\n*/\n\n# response below will return report for ledger range: (6873345-256) to 6873344\n$response = $reader-\u003efetchSingle(6873342);\n$response = $reader-\u003efetchSingle(6873343);\n$response = $reader-\u003efetchSingle(6873344); //flag ledger\n# response below will return report for ledger range: 6873345 to (6873344+256)\n$response = $reader-\u003efetchSingle(6873345);\n$response = $reader-\u003efetchSingle(6873346);\n// ...\n```\n\n### Fetching multiple reports\nThis is more optimized way to fetch multiple reports than doing loop and using `fetchSingle()`, since this script uses Promises to asynchronously query node in batches, default batch limit is 10 but can be configured manually.\n\n```PHP\nuse XRPLWin\\UNLReportReader\\UNLReportReader;\n\n//this will set async batch limit to 5 (down from default 10)\n$reader = new UNLReportReader('https://xahau-test.net',['async_batch_limit' =\u003e 5]);\n\n$forward = true;\n$limit = 2;\n$response = $reader-\u003efetchMulti(6873340, $forward, $limit); //array\n\n//Ledger index \"6873340\" is between 6873345 and 6873600\n\n/*\nSAMPLE RESPONSE:\narray:2 [\n  0 =\u003e array:4 [\n    \"flag_ledger_index\" =\u003e 6873344\n    \"flag_ledger_close_time\" =\u003e 748969761\n    \"report_range\" =\u003e array:2 [\n      0 =\u003e 6873345\n      1 =\u003e 6873600\n    ]\n    \"import_vlkey\" =\u003e \"ED264807102805220DA0F312E71FC2C69E1552C9C5790F6C25E3729DEB573D5860\"\n    \"active_validators\" =\u003e array:7 [\n      0 =\u003e array:2 [\n        \"Account\" =\u003e \"rGhk2uLd8ShzX2Zrcgn8sQk1LWBG4jjEwf\"\n        \"PublicKey\" =\u003e \"ED3ABC6740983BFB13FFD9728EBCC365A2877877D368FC28990819522300C92A69\"\n      ]\n      1 =\u003e array:2 [\n        \"Account\" =\u003e \"rnr4kwS1VkJhvjVRuq2fbWZtEdN2HbpVVu\"\n        \"PublicKey\" =\u003e \"ED49F82B2FFD537F224A1E0A10DEEFC3C25CE3882979E6B327C9F18603D21F0A22\"\n      ]\n      2 =\u003e array:2 [\n        \"Account\" =\u003e \"rJupFrPPYgUNFBdoSqhMEJ22hiHKiZSHXQ\"\n        \"PublicKey\" =\u003e \"ED79EB0F6A9F01A039235E536D19F812B55ACF540C9E22CF62C271E0D42BFF5174\"\n      ]\n      3 =\u003e array:2 [\n        \"Account\" =\u003e \"roUo3ygV92bdhfE1v9LGpPETXvJv2kQv5\"\n        \"PublicKey\" =\u003e \"ED93B2BE467CAD2F9F56FB3A82BDFF17F84B09E34232DDE8FAF2FC72382F142655\"\n      ]\n      4 =\u003e array:2 [\n        \"Account\" =\u003e \"rGsa7f4arJ8JE9ok9LCht6jCu5xBKUKVMq\"\n        \"PublicKey\" =\u003e \"ED96F581FED430E8CBE1F08B37408857001D4118D49FBB594B0BE007C2DBFFD367\"\n      ]\n      5 =\u003e array:2 [\n        \"Account\" =\u003e \"r3htgPchiR2r8kMGzPK3Wfv3WTrpaRKjtU\"\n        \"PublicKey\" =\u003e \"EDCF31B8F683345E1C49B4A1D85BF2731E55E7D6781F3D4BF45EE7ADF2D2FB3402\"\n      ]\n      6 =\u003e array:2 [\n        \"Account\" =\u003e \"rfQtB8m51sdbWgcmddRX2mMjMpSxzX1AGr\"\n        \"PublicKey\" =\u003e \"EDDF197FC59A7FAA09EB1AD60A4638BA6201DD51497B5C08A1745115098E229E0E\"\n      ]\n    ]\n  ]\n  1 =\u003e array:4 [\n    \"flag_ledger_index\" =\u003e 6873600\n    \"flag_ledger_close_time\" =\u003e 748970540\n    \"report_range\" =\u003e array:2 [\n      0 =\u003e 6873601\n      1 =\u003e 6873856\n    ]\n    \"import_vlkey\" =\u003e \"ED264807102805220DA0F312E71FC2C69E1552C9C5790F6C25E3729DEB573D5860\"\n    \"active_validators\" =\u003e array:7 [\n      0 =\u003e array:2 [\n        \"Account\" =\u003e \"rGhk2uLd8ShzX2Zrcgn8sQk1LWBG4jjEwf\"\n        \"PublicKey\" =\u003e \"ED3ABC6740983BFB13FFD9728EBCC365A2877877D368FC28990819522300C92A69\"\n      ]\n      1 =\u003e array:2 [\n        \"Account\" =\u003e \"rnr4kwS1VkJhvjVRuq2fbWZtEdN2HbpVVu\"\n        \"PublicKey\" =\u003e \"ED49F82B2FFD537F224A1E0A10DEEFC3C25CE3882979E6B327C9F18603D21F0A22\"\n      ]\n      2 =\u003e array:2 [\n        \"Account\" =\u003e \"rJupFrPPYgUNFBdoSqhMEJ22hiHKiZSHXQ\"\n        \"PublicKey\" =\u003e \"ED79EB0F6A9F01A039235E536D19F812B55ACF540C9E22CF62C271E0D42BFF5174\"\n      ]\n      3 =\u003e array:2 [\n        \"Account\" =\u003e \"roUo3ygV92bdhfE1v9LGpPETXvJv2kQv5\"\n        \"PublicKey\" =\u003e \"ED93B2BE467CAD2F9F56FB3A82BDFF17F84B09E34232DDE8FAF2FC72382F142655\"\n      ]\n      4 =\u003e array:2 [\n        \"Account\" =\u003e \"rGsa7f4arJ8JE9ok9LCht6jCu5xBKUKVMq\"\n        \"PublicKey\" =\u003e \"ED96F581FED430E8CBE1F08B37408857001D4118D49FBB594B0BE007C2DBFFD367\"\n      ]\n      5 =\u003e array:2 [\n        \"Account\" =\u003e \"r3htgPchiR2r8kMGzPK3Wfv3WTrpaRKjtU\"\n        \"PublicKey\" =\u003e \"EDCF31B8F683345E1C49B4A1D85BF2731E55E7D6781F3D4BF45EE7ADF2D2FB3402\"\n      ]\n      6 =\u003e array:2 [\n        \"Account\" =\u003e \"rfQtB8m51sdbWgcmddRX2mMjMpSxzX1AGr\"\n        \"PublicKey\" =\u003e \"EDDF197FC59A7FAA09EB1AD60A4638BA6201DD51497B5C08A1745115098E229E0E\"\n      ]\n    ]\n  ]\n]\n*/\n```\n\n### Fetching multiple reports between ledgers\n\n```PHP\nuse XRPLWin\\UNLReportReader\\UNLReportReader;\n\n$reader = new UNLReportReader('https://xahau-test.net');\n\n//ledger start, ledger end\n$response = $reader-\u003efetchRange(6100000, 6200000); //array\n```\n\n### Checking ledger edge (incomplete results)\nWhen checking ledger edge, eg. you requested ledger index that does not yet exists this is how will you check existance:\n\n**For single ledger**\n```PHP\n//this will return null if ledger_index is out of range\n$response = $reader-\u003efetchSingle(9873344);\nif($response === null) {\n  //Incomplete result\n}\n```\n**For multiple ledgers**\n```PHP\n$requested_limit = 10;\n//this will return less results than requested if some or all ledgers are out of range\n$response = $reader-\u003efetchMulti(9873344,true,$requested_limit);\nif(count($response) != $requested_limit) {\n  //Incomplete result\n}\n```\n**For range**\n```PHP\n$fromLedgerIndex = 6100000;\n$toLedgerIndex = 6200000;\n\n//this will give you exact limit that will be sent to -\u003efetchMulti() method\n$calculated_limit = UNLReportReader::calcNumFlagsBetweenLedgers(\n  UNLReportFlagLedger::nextOrCurrent($fromLedgerIndex),\n  UNLReportFlagLedger::nextOrCurrent($toLedgerIndex)\n);\n$response = $reader-\u003efetchRange($fromLedgerIndex, $toLedgerIndex); //array\nif(count($response) != $calculated_limit) {\n  //Incomplete result\n}\n```\n\n## Special thanks\n\n[@richardAH](https://github.com/richardAH) - Thank you 🙏 for in-depth explanation and support.  \n[@dangell7](https://github.com/dangell7) - Thank you 🙏 for great insight.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxrplwin%2Funlreportreader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxrplwin%2Funlreportreader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxrplwin%2Funlreportreader/lists"}