{"id":19070875,"url":"https://github.com/ohager/signumfs","last_synced_at":"2026-02-17T05:02:36.904Z","repository":{"id":174998305,"uuid":"652185904","full_name":"ohager/signumfs","owner":"ohager","description":"Signum File System","archived":false,"fork":false,"pushed_at":"2023-06-14T19:05:45.000Z","size":909,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-12T06:06:13.106Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ohager.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-06-11T11:14:28.000Z","updated_at":"2025-08-23T17:49:19.000Z","dependencies_parsed_at":"2023-07-08T13:46:21.099Z","dependency_job_id":null,"html_url":"https://github.com/ohager/signumfs","commit_stats":null,"previous_names":["ohager/signumfs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ohager/signumfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohager%2Fsignumfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohager%2Fsignumfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohager%2Fsignumfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohager%2Fsignumfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ohager","download_url":"https://codeload.github.com/ohager/signumfs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohager%2Fsignumfs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29534471,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T05:00:25.817Z","status":"ssl_error","status_checked_at":"2026-02-17T04:57:16.126Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-11-09T01:21:05.509Z","updated_at":"2026-02-17T05:02:36.886Z","avatar_url":"https://github.com/ohager.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=ohager_signumfs\u0026metric=code_smells)](https://sonarcloud.io/summary/new_code?id=ohager_signumfs)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=ohager_signumfs\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=ohager_signumfs)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=ohager_signumfs\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=ohager_signumfs)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=ohager_signumfs\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=ohager_signumfs)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=ohager_signumfs\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=ohager_signumfs)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ohager_signumfs\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=ohager_signumfs)\n\n# SignumFS\n\nA simple on-chain file storage solution for the best [unknown blockchain platform](https://signum.network).\n\n## Motivation\n\nThe Signum blockchain is capable of storing arbitrary data on-chain. Each transaction can carry up to 1000 bytes of data.\nSo, why not splitting files into multiple transactions and store them on-chain?\n\nMind, that the data is publicly available and (at current time of writing) no additional encryption is considered.\nData can be compressed (using Brotli) optionally, but also keep in mind, that most media types are already compressed efficiently.\nCompression makes sense for textual data.\n\n## Installation\n\n\u003e Requires Node 16+ installed\n\nJust run `npm i signumfs -g`\n\n## CLI Usage\n\n`signumfs --help` to get more info\n\n```\nUsage: signumfs [options] [command]\n\n\n            @@@@@@@@  @@@@@@@\n         @@@@@    @@@@@    @@@@@\n           @@@  @@@  @@@ @@@@@\n    @@@      @@@@@     @@@@       @@@\n  @@@@@@@@ \u0026@@@  @@@@@@@@ @@@@  @@@@@@@\n @@@    @@@@       @@@      @@@@@    @@@\n @@@  @@@ *@@@@           @@@  @@@  @@@@\n   @@@@@     @@@         @@@     @@@@@\n @@@@  @@@  @@@           @@@@  @@@  @@@\n @@@    @@@@@      @@@       @@@@    @@@\n  @@@@@@@  @@@  @@@@@@@@  @@@  @@@@@@@@\n    @@@       @@@@     @@@@@      @@@\n           @@@@  @@@  @@@  @@@\n         @@@@@    @@@@@    @@@@@\n            @@@@@@@  @@@@@@@@\n\n     SignumFS - Blockchain File Storage\n\n  Author: ohager\n  Version: 1.0.1\n\n\nOptions:\n  -V, --version          output the version number\n  -h, --help             display help for command\n\nCommands:\n  upload|up [options]    Upload a file\n  download|dl [options]  Download a file\n  list|ls [options]      List all uploaded files\n  profile\n  help [command]         display help for command\n\n```\n\n\u003e Credits to [CurbShifter](https://github.com/CurbShifter) who inspired me for this tool. He did something similar back in 2018\n\n### Profile\n\nBefore you start you need to create your profile, i.e. storing your account data and set node url\nJust run `signumfs profile init` and follow the guides\n\nYou can always `reset` and `show` your profile.\n\n### Files\n\nAt this moment, only three simple commands are available\n\n#### Upload\n\n\u003e Consider the [limitations](#limits-and-considerations) and also the [Disclaimer](#disclaimer)\n\n```\nUsage: signumfs upload|up [options]\n\nUpload a file\n\nOptions:\n-t, --try            Runs without creating anything on chain. Good for testing purposes and checking costs\n-f, --file \u003cstring\u003e  Filename to upload\n-x, --compress       Compress data before upload\n-h, --help           display help for command\n```\n\nExample:\n\nUploads an image. Compression usually makes no sense, unless it's SVG\n\n```bash\nsignumfs up -f ohager_avatar.png\n\n? Enter your PIN [hidden]\n✔ Uploaded Successfully\n┌──────────┬────────────────────────┐\n│ (index)  │         Values         │\n├──────────┼────────────────────────┤\n│   fee    │         '4.47'         │\n│  fileId  │ '12973307999043577690' │\n│  chunks  │           79           │\n│ uploaded │      '76.38 KiB'       │\n└──────────┴────────────────────────┘\n```\n\nUploads a file with compression on. Text files can be dramatically reduced in size (\u003e50% is not rare)!\n\n```bash\nsignumfs up -f sometextfile.md -x\n```\n\n#### Download\n\n```\nUsage: signumfs download|dl [options]\n\nDownload a file\n\nOptions:\n  -f, --fileId \u003cstring\u003e   File Chain Id\n  -o, --outfile \u003cstring\u003e  Custom File Name\n  -h, --help              display help for command\n```\n\n**Examples**\n\nSimple download\n\n```bash\nsignumfs download --fileId 12973307999043577690\n? Enter your PIN [hidden]\n✔ Downloaded Successfully\nFile saved under: ohager_bat.png\n```\n\nDownloads to a custom file name\n\n```bash\nsignumfs dl -f 12973307999043577690 -o ohager_signum_avatar.png\n? Enter your PIN [hidden]\n✔ Downloaded Successfully\nFile saved under: /home/ohager/Pictures/ohager_signum_avatar.png\n```\n\n### List Files\n\n```\nUsage: signumfs list|ls [options]\n\nList all uploaded files\n\nOptions:\n  -a, --account \u003cstring\u003e  Account Id, Address, or alias. If not given your own profile account is considered (default: \"\")\n  -h, --help              display help for command\n```\n\n**Examples**\n\nList your own files\n\n```bash\nsignumfs ls\n? Enter your PIN [hidden]\n✔ Fetched 1 file records for 9K9L-4CB5-88Y5-F5G4Z\n┌─────────┬────────────────────────┬──────────────────┬───────┬──────┬────────┬────────────┬─────────────────────────┐\n│ (index) │         fileId         │       name       │ size  │ fee  │ chunks │ compressed │         sha512          │\n├─────────┼────────────────────────┼──────────────────┼───────┼──────┼────────┼────────────┼─────────────────────────┤\n│    0    │ '12973307999043577690' │ 'ohager_bat.png' │ 78215 │ 4.46 │   79   │    '-'     │ '2b26642e30…a5823809dd' │\n└─────────┴────────────────────────┴──────────────────┴───────┴──────┴────────┴────────────┴─────────────────────────┘\n```\n\nList files of other accounts - you can use accountIds, addresses and also aliases (with TLD support: `\u003calias\u003e:\u003ctld\u003e`)\n\n```bash\nsignumfs ls --account  S-9K9L-4CB5-88Y5-F5G4Z\n? Enter your PIN [hidden]\n✔ Fetched 1 file records for 9K9L-4CB5-88Y5-F5G4Z\n┌─────────┬────────────────────────┬──────────────────┬───────┬──────┬────────┬────────────┬─────────────────────────┐\n│ (index) │         fileId         │       name       │ size  │ fee  │ chunks │ compressed │         sha512          │\n├─────────┼────────────────────────┼──────────────────┼───────┼──────┼────────┼────────────┼─────────────────────────┤\n│    0    │ '12973307999043577690' │ 'ohager_bat.png' │ 78215 │ 4.46 │   79   │    '-'     │ '2b26642e30…a5823809dd' │\n└─────────┴────────────────────────┴──────────────────┴───────┴──────┴────────┴────────────┴─────────────────────────┘\n```\n\nUsing alias with tld\n\n```bash\nsignumfs ls -a nostrd00d:nostr\n? Enter your PIN [hidden]\n✔ Fetched 1 file records for 9K9L-4CB5-88Y5-F5G4Z\n┌─────────┬────────────────────────┬──────────────────┬───────┬──────┬────────┬────────────┬─────────────────────────┐\n│ (index) │         fileId         │       name       │ size  │ fee  │ chunks │ compressed │         sha512          │\n├─────────┼────────────────────────┼──────────────────┼───────┼──────┼────────┼────────────┼─────────────────────────┤\n│    0    │ '12973307999043577690' │ 'ohager_bat.png' │ 78215 │ 4.46 │   79   │    '-'     │ '2b26642e30…a5823809dd' │\n└─────────┴────────────────────────┴──────────────────┴───────┴──────┴────────┴────────────┴─────────────────────────┘\n```\n\n## API Usage\n\nYou can use the `SignumFS` class programmatically, having three methods\n\n- `uploadFile`\n- `downloadFile`\n- `listFiles`\n\n```ts\nconst fs = new SignumFS({\n  dryRun: false,\n  seed: \"\u003cyour_seed\u003e\",\n  nodeHost: \"https://localhost:8125\",\n});\n\n// saves from ledger into ./myfile.downloaded.txt\nconst metadata = await fs.downloadFile({\n  metadataTransactionId: \"1234\", // transaction Id of the on-chain metadata\n  filePath: \"./myfile.downloaded.txt\",\n});\n\n// uploads file to ledger\nconst uploadinfo = await fs.uploadFile({\n  file: \"./myfile.txt\",\n  shouldCompress: true,\n});\n\n// list file records per account\nconst fileRecords = await fs.uploadFile(\"\u003caccountId\u003e\");\n```\n\n\u003e See more in the [API Doc](https://ohager.github.io/signumfs/)\n\n## Limits and Considerations\n\nAs space is a valuable resource on blockchain certain costs are involved: ~0.06 SIGNA/kB\nFurthermore, upload file size is limited to 1 MiB at the moment,\nresulting in 1,057 transactions à 0.06 SIGNA + 1 transaction à 0.02 SIGNA, summing up to 63.44 SIGNA.\nTo not congest the chain the maximum amount of transactions per block is set to 160 per default.\nSo, full 1 MiB would be split into 7 Blocks each taking in avg. 4 minutes until confirmed.\nSo taking ~28 Minutes until the entire file is confirmed by the network.\n\n### Local Node\n\nAlthough you could use public nodes to upload, you should always use a local node:\n\n- faster\n- more stable\n- allow custom config\n\n#### Configuration\n\nWhen uploading larger files you might hit a limit on maximum referenced transactions reached:\n\n```\n[INFO] 2023-06-14 09:23:45 brs.unconfirmedtransactions.UnconfirmedTransactionStoreImpl - Transaction -3662528926404861624: Not added because too many transactions with referenced full hash\n```\n\nThe default value is 5% of 8192 (cache transaction limit), which is about 400 references. The block splitting uses referenced transactions,\nso you might end up hitting the limit on a 1 MiB file. You can raise the limit in your configuration file:\n\n```\nP2P.maxUnconfirmedTransactionsFullHashReferencePercentage=15\n```\n\n# Disclaimer\n\n\u003cem\u003e\nPlease read the following terms and conditions carefully before using the file upload tool for the public blockchain. By using this tool, you acknowledge that you have understood and agreed to the terms outlined below:\n\n**Public Nature of Data**:\nThe public blockchain operates on a decentralized network where uploaded files become publicly accessible to all users. Any data uploaded using this tool will be visible to anyone accessing the blockchain. Therefore, do not upload any information that you wish to remain private or confidential.\n\n**Prohibited Content**:\nYou are strictly prohibited from uploading any violent, illegal, or harmful content using this tool. This includes, but is not limited to, explicit material, hate speech, copyrighted content without proper authorization, and any content that violates applicable laws or regulations. The tool must only be used for lawful and ethical purposes.\n\n**No Liability**:\nThe creator of this software tool cannot be held responsible or liable for any misuse, unauthorized access, or content uploaded by users. You understand and agree that you are solely responsible for the files you upload to the public blockchain. The creator of the software cannot guarantee the accuracy, reliability, or security of the uploaded content.\n\n**\"As Is\" Basis**:\nThis software tool is provided \"as is\" without any warranties or guarantees of any kind, either expressed or implied. The creator of the software does not warrant that the tool will be error-free, secure, or continuously available. Any reliance on the tool and its functionality is at your own risk.\n\nBy using this tool, you acknowledge that you have read, understood, and agreed to the terms and conditions outlined in this disclaimer. If you do not agree with any part of this disclaimer, please refrain from using the tool to upload files to the public blockchain.\n\n\u003c/em\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohager%2Fsignumfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fohager%2Fsignumfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohager%2Fsignumfs/lists"}