{"id":13839389,"url":"https://github.com/0xsequence/sstore2","last_synced_at":"2025-07-11T03:32:07.852Z","repository":{"id":37935626,"uuid":"414262361","full_name":"0xsequence/sstore2","owner":"0xsequence","description":"Faster \u0026 cheaper contract key-value storage for Ethereum Contracts","archived":false,"fork":false,"pushed_at":"2022-06-14T18:48:50.000Z","size":423,"stargazers_count":421,"open_issues_count":7,"forks_count":31,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-08-05T17:23:36.906Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/0xsequence.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-10-06T15:12:08.000Z","updated_at":"2024-07-29T10:38:34.000Z","dependencies_parsed_at":"2022-06-26T15:47:28.346Z","dependency_job_id":null,"html_url":"https://github.com/0xsequence/sstore2","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsequence%2Fsstore2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsequence%2Fsstore2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsequence%2Fsstore2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsequence%2Fsstore2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xsequence","download_url":"https://codeload.github.com/0xsequence/sstore2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225675073,"owners_count":17506273,"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-08-04T17:00:21.413Z","updated_at":"2024-11-21T04:30:37.939Z","avatar_url":"https://github.com/0xsequence.png","language":"JavaScript","funding_links":[],"categories":["Electricity, Sustainability, Gas"],"sub_categories":[],"readme":"# SLOAD2 \u0026 SLOAD2-Map\n\n![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)\n[![tests](https://github.com/0xsequence/sstore2/actions/workflows/tests.yml/badge.svg)](https://github.com/0xsequence/sstore2/actions/workflows/tests.yml)\n\nSLOAD2 is a set of Solidity libraries for writing and reading contract storage paying a fraction of the cost, it uses contract code as storage, writing data takes the form of contract creations and reading data uses `EXTCODECOPY`.\n\n\u003e **The library is not audited, it's recommended to perform a full audit of SSTORE2 and CREATE3 before using this code on a production envirovment.**\n\n## Features\n\n- All SLOAD2 storages are write-once only\n- Key Value storage (custom key and auto-gen key)\n- Cheaper storage reads (vs SLOAD) after 32 bytes\n- Cheaper storage writes (vs SSTORE) after 32 bytes (auto-gen key)\n- Cheaper storage writes (vs SSTORE) after 96 bytes (custom key)\n- Use strings as keys\n- Use bytes32 as keys\n- Use address as keys (auto-gen)\n\n## Gas savings\n\nGas costs are overall lower compared with traditional SSTORED and SLOAD operations, SLOAD2 (auto-generated key) and SLOAD2-Map (custom key) have different costs associated with using them.\n\nThe root cause is that custom-key SLOAD2 needs to use CREATE3 to deploy the data contract, and CREATE3 needs to deploy an aditional proxy contract for each deployed contract.\n\n### SLOAD Cost (data read)\n\nReading data is a lot cheaper compared to native SLOAD operations (native solidity storage).\n\nAfter reading 32 bytes `SSTORE2.read` becomes the cheaper option, and `SSTORE2Map.read` becomes cheaper when reading 33 bytes or more.\n\n| Size (bytes) | SLOAD     | SLOAD2 | SLOAD2 - Map | Savings | Savings (map) |\n|--------------|-----------|--------|--------------|---------|---------------|\n|            0 |     2.679 |  3.102 |        5.258 |   0,86x |         0,51x |\n|            2 |     2.852 |  3.108 |        5.261 |   0,92x |         0,54x |\n|           32 |     4.914 |  3.108 |        5.264 |   1,58x |         0,93x |\n|           33 |     7.067 |  3.114 |        5.267 |   2,27x |         1,34x |\n|           64 |     7.067 |  3.114 |        5.270 |   2,27x |         1,34x |\n|           96 |     9.220 |  3.120 |        5.276 |   2,96x |         1,75x |\n|          128 |    11.373 |  3.126 |        5.282 |   3,64x |         2,15x |\n|          256 |    19.985 |  3.150 |        5.306 |   6,34x |         3,77x |\n|          512 |    37.209 |  3.198 |        5.355 |  11,64x |         6,95x |\n|         1024 |    71.659 |  3.296 |        5.454 |  21,74x |        13,14x |\n|        24576 | 1.349.161 |  7.627 |        9.805 | 176,89x |       137,60x |\n\n![SSTORE Cost](./images/sload_cost.svg)\n\n### SSTORE Cost (data writes)\n\nWriting data is also cheaper than native SSTORE operations (native solidity storage), but gains become apparent after higher data sizes.\n\nAfter writing 32 bytes `SSTORE2.write` becomes the cheaper option, and `SSTORE2Map.write` becomes cheaper only when writing 128 bytes or more.\n\n| Size (bytes) | SSTORE     | SSTORE2   | SSTORE2 - Map | Savings | Savings (map) |\n|--------------|------------|-----------|---------------|---------|---------------|\n|            0 |      2.660 |    35.323 |        73.565 |   0,08x |         0,04x |\n|            2 |     22.607 |    35.819 |        74.061 |   0,63x |         0,31x |\n|           32 |     44.810 |    41.891 |        80.218 |   1,07x |         0,56x |\n|           33 |     66.980 |    42.187 |        80.514 |   1,59x |         0,83x |\n|           64 |     66.980 |    48.459 |        86.870 |   1,38x |         0,77x |\n|           96 |     89.150 |    55.027 |        93.523 |   1,62x |         0,95x |\n|          128 |    111.320 |    61.595 |       100.175 |   1,81x |         1,11x |\n|          256 |    200.000 |    87.869 |       126.786 |   2,28x |         1,58x |\n|          512 |    377.360 |   140.417 |       180.010 |   2,69x |         2,10x |\n|         1024 |    732.080 |   245.522 |       286.475 |   2,98x |         2,56x |\n|        24576 | 13.878.890 | 4.148.020 |     4.244.998 |   3,35x |         3,27x |\n\n![SSTORE Cost](./images/sstore_cost.svg)\n\n\u003e **Notice:** gas savings may change in future Ethereum hard-forks.\n\n\u003e **Notice x2:** due to contract code limits 24576 bytes is the maximum amount of data that can be written in a single pointer / key. Attempting to write more will result in failure.\n\n## Installation\n\n`yarn add https://github.com/0xsequence/sstore2`\n\nor\n\n`npm install --save https://github.com/0xsequence/sstore2`\n\n## Usage\n\nSSTORE2 comes in two flavors, `SSTORE2` and `SSTORE2Map`. The main difference is that `SSTORE2` auto-generates a key or \"pointer\" for later data reads, and `SSTORE2Map` let's you use a custom pointer in the form of a `bytes32` key.\n\n`SSTORE2` is cheaper because it only needs to use `CREATE`. `SSTORE2Map` is a little more expensive (~ +50k gas) because it makes use of [CREATE3](https://github.com/0xsequence/create3), which requires using both CREATE2 + CREATE at the same time.\n\n\n## SSTORE2\n\nCalling `SSTORE2.write` with some `data` returns an `address` pointer; this pointer address can later be feed into `SSTORE2.read` to retrieve the same `data`. Every time `write` is called it generates a new pointer, pointers can't be deleted.\n\n\u003e Notice: reading a never an invalid pointer may return an empty bytes array **or** contract bytecode.\n\n```solidity\npragma solidity ^0.8.0;\n\nimport \"@0xsequence/sstore2/contracts/SSTORE2.sol\";\n\n\ncontract Demo {\n  address private pointer;\n\n  function setText(string calldata _text) external {\n    pointer = SSTORE2.write(bytes(_text));\n  }\n\n  function getText() external view returns (string memory) {\n    return string(SSTORE2.read(pointer));\n  }\n}\n```\n\n### Arbitrary size immutables\n\nSolidity 0.8.9 doesn't support variable size immutable variables; these can be emulated using SSTORE2 and immutable pointers.\n\n```solidity\npragma solidity ^0.8.0;\n\nimport \"@0xsequence/sstore2/contracts/SSTORE2.sol\";\n\n\ncontract Demo {\n  address private immutable dataPointer;\n\n  constructor(bytes memory _data) {\n    dataPointer = SSTORE2.write(_data);\n  }\n\n  function getData() external view returns (bytes memory) {\n    return SSTORE2.read(dataPointer);\n  }\n}\n\ncontract Broken {\n  // Fails to build, non-primite types\n  // can't be used as immutable variables\n\n  bytes private immutable data;\n\n  constructor(bytes memory _data) {\n    data = _data;\n  }\n}\n\n```\n\n## SSTORE2Map\n\nSSTORE2Map behaves similarly to SSTORE2, but instead of auto-generating a pointer on each `SSTORE2Map.write` call it takes an arbitrary `key` in the form of a `bytes32` variable; this key must later be provided to `SSTORE2Map.read` to retrieve the written value.\n\nThe map store is also write-once, meaning that calling `SSTORE2Map.write` TWICE with the same key will fail. There is no mechanism for deleting or removing the value of a given key.\n\n\u003e Notice: reading a never written key will always return an empty array of bytes.\n\n```solidity\npragma solidity ^0.8.0;\n\nimport \"@0xsequence/sstore2/contracts/SSTORE2Map.sol\";\n\n\ncontract Demo {\n  bytes32 private constant KEY = 0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3;\n\n  function setHashes(bytes32[] calldata _hashes) external {\n    SSTORE2Map.write(KEY, abi.encode(_hashes));\n  }\n\n  function getHashes() external view returns (bytes32[] memory) {\n    return abi.decode(SSTORE2Map.read(KEY), (bytes32[]));\n  }\n}\n\n```\n\n### Using multiple keys\n\nSSTORE2Map supports using multiple keys at the same time, but re-using a key will result in failure.\n\n```solidity\npragma solidity ^0.8.0;\n\nimport \"@0xsequence/sstore2/contracts/SSTORE2Map.sol\";\n\n\ncontract Demo {\n  // This works\n  function good() external {\n    SSTORE2Map.write(string(\"@key-1\"), bytes(\"hola\"));\n    SSTORE2Map.write(string(\"@key-2\"), bytes(\"mundo\"));\n  }\n\n  // This reverts\n  function bad() external {\n    SSTORE2Map.write(string(\"@key-3\"), bytes(\"adios\"));\n    SSTORE2Map.write(string(\"@key-3\"), bytes(\"mundo\"));\n  }\n}\n\n```\n\n\u003e Notice: `strings` can be used as `SSTORE2Map`; they get internally mapped as `keccak256(bytes(\u003cstring\u003e)`.\n\n# Reading slices\n\nBoth `SSTORE2` and `SSTORE2Map` support reading data slices; their behaviors mirror javascript's `.slice(start, end)`.\n\nThe functionality can be used for future-proofing a contract in the case that code merkelization is ever implemented.\n\n```solidity\npragma solidity ^0.8.0;\n\nimport \"@0xsequence/sstore2/contracts/SSTORE2.sol\";\n\n\ncontract Demo {\n  event Sliced(bytes _data);\n\n  function goodSlices() external {\n    address pointer = SSTORE2.write(hex\"11_22_33_44\");\n\n    // 0x223344\n    emit Sliced(\n      SSTORE2.read(pointer, 1)\n    );\n\n    // 0x2233\n    emit Sliced(\n      SSTORE2.read(pointer, 1, 3)\n    );\n\n    // 0x\n    emit Sliced(\n      SSTORE2.read(pointer, 3, 3)\n    );\n\n    // 0x3344\n    emit Sliced(\n      SSTORE2.read(pointer, 2, 42000)\n    );\n\n    // 0x\n    emit Sliced(\n      SSTORE2.read(pointer, 41000, 42000)\n    );\n  }\n\n  function badSlies() external {\n    address pointer = SSTORE2.write(hex\"11_22_33_44\");\n\n    // This reverts\n    // start must be equal or lower than end\n    emit Sliced(\n      SSTORE2.read(pointer, 3, 2)\n    );\n  }\n}\n\n```\n\n# License\n\n```\nMIT License\n\nCopyright (c) [2018] [Ismael Ramos Silvan]\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xsequence%2Fsstore2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xsequence%2Fsstore2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xsequence%2Fsstore2/lists"}