{"id":28630852,"url":"https://github.com/aztecprotocol/huff","last_synced_at":"2025-06-12T13:08:56.174Z","repository":{"id":41086485,"uuid":"167074174","full_name":"AztecProtocol/huff","owner":"AztecProtocol","description":"Repository for Huff - an EVM programming language","archived":false,"fork":false,"pushed_at":"2020-02-24T23:03:54.000Z","size":182,"stargazers_count":235,"open_issues_count":1,"forks_count":25,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-06-05T23:36:17.513Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AztecProtocol.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}},"created_at":"2019-01-22T22:01:47.000Z","updated_at":"2025-03-11T08:58:32.000Z","dependencies_parsed_at":"2022-07-18T05:46:15.576Z","dependency_job_id":null,"html_url":"https://github.com/AztecProtocol/huff","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AztecProtocol/huff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AztecProtocol%2Fhuff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AztecProtocol%2Fhuff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AztecProtocol%2Fhuff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AztecProtocol%2Fhuff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AztecProtocol","download_url":"https://codeload.github.com/AztecProtocol/huff/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AztecProtocol%2Fhuff/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259470959,"owners_count":22862999,"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":"2025-06-12T13:08:54.088Z","updated_at":"2025-06-12T13:08:56.147Z","avatar_url":"https://github.com/AztecProtocol.png","language":"JavaScript","readme":"## **Huff**: a programming language for the Ethereum Virtual Machine\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://i.imgur.com/SVRjUhU.png\" width=\"640px\"/\u003e\u003c/p\u003e\n\nHuff is a domain-specific language created for the purposes of writing highly optimized Ethereum Virtual Machine program code and, ultimately, smart contracts.\n\nHuff enables the construction of EVM assembly macros - blocks of bytecode that can be rigorously tested and evaluated. Macros can themselves be composed of Huff macros.\n\nHuff doesn't hide the workings of the EVM behind syntactic sugar. In fact, Huff doesn't hide anything at all. Huff does not have variables, instead directly exposing the EVM's program stack to the developer to be directly manipulated.\n\n### **\"Wait...that sounds terrible! What is the point of huff?\"**\n\nI developed Huff while writing [weierstrudel](https://github.com/AztecProtocol/weierstrudel/tree/master/huff_modules), an elliptic curve arithmetic library. Huff is designed for developing highly optimized algorithms where direct manipulation of the program's bytecode is preferred.\n\nHuff supports a form of templating - Huff macros can accept template parameters, which in turn are Huff macros. This allows for customizable macros that are ideal for loop unrolling.\n\nHuff algorithms can be broken down into their constituent macros and rigorously tested without having to split the algorithm into functions and invoke jump instructions.\n\n### **Huff syntax**\n\nThere are only two fundamental building blocks to a Huff program:\n\n-   Macros\n-   Jump tables (and packed jump tables)\n-   (TODO: add bytecode tables)\n\n### **Macros**\n\nSome example macros:\n\n```\n#define macro P = takes(0) returns(1) {\n    0x30644E72E131A029B85045B68181585D97816A916871CA8D3C208C16D87CFD47\n}\n\n#define macro P_LOCATION = takes(0) returns(1) {\n    0x20\n}\n\n#define macro GET_P = takes(0) returns(1) {\n    P_LOCATION() mload\n}\n\ntemplate \u003cp1,p2\u003e\n#define macro POINT_DOUBLE = takes(3) returns(3) {\n    \u003cp1\u003e dup3 callvalue shl\n    swap3 dup4 mulmod\n    \u003cp2\u003e dup2 callvalue shl\n    dup2 dup1 dup1 dup4 dup10\n    mulmod dup2 sub swap8\n    dup1 mulmod 0x03 mul\n    dup2 dup2 dup1\n    mulmod dup9 callvalue shl add swap8\n    dup9 add mulmod swap3 mulmod add swap2\n    \u003cp2\u003e swap2 mulmod \u003cp1\u003e sub\n}\n\n#define macro POINT_DOUBLE_IMPLEMENTATIONS = takes(3) returns(3) {\n    P()\n    dup1 P_LOCATION() mstore\n    0x01 // x\n    0x02 // y\n    0x01 // z\n    POINT_DOUBLE\u003cdup4, dup5\u003e()\n    POINT_DOUBLE\u003cP, P\u003e()\n    POINT_DOUBLE\u003cGET_P, P\u003e()\n}\n```\n\nThe `takes` parameter defines the number of items the macro expects to be on the stack.  \nThe `returns` parameter defines the number of items the macro will leave on the stack (including the items from `takes`).  \nThese fields are for illustrative purposes only - they are not enforced by the compiler, as that would inhibit macros where the stack state is unknowable at compile time. Some languages might consider that a negative, but not Huff.\n\n### **Jump tables**\n\nHuff supports tables of jump destinations integrated directly into the contract bytecode. This is to enable efficient program execution flows by using jump tables instead of conditional branching.\n\nAn example:\n\n```\n#define jumptable JUMP_TABLE {\n    lsb_0 lsb_1 lsb_2 lsb_1 lsb_3 lsb_1\n    lsb_2 lsb_1 lsb_4 lsb_1 lsb_2 lsb_1\n    lsb_3 lsb_1 lsb_2 lsb_1\n}\n\n#define macro EXAMPLE = takes(0) returns(0) {\n    0x01\n    __tablesize(JUMP_TABLE) __tablestart(JUMP_TABLE) 0x00 codecopy\n    0x00 calldataload mload jump\n\n    lsb_0:\n        0x01 add\n    lsb_1:\n        0x02 add\n    lsb_2:\n        0x03 add\n    lsb_3:\n        0x04 add\n    lsb_4:\n        0x05 add\n}\n```\n\nJump labels will by default occupy 32-bytes of space in the contract bytecode. Packed jump tables, where each label occupies 2 bytes, can be created via `#define jumptable__packed`.\n\n### **Additional features**\n\nHuff currently supports three pieces of syntactic sugar:\n\n-   `__codesize(MACRO_NAME)` will push the size of a given macro (in bytes) onto the stack.\n-   `__tablesize(TABLE_NAME)` will push the size of a given table (in bytes) onto the stack.\n-   `__tablestart(TABLE_NAME)` will push the offset (in bytes) between the start of the contract's bytecode and the location of the given table onto the stack.\n\nIn addition, when supplying templated arguments to a macro, `+`, `-` and `*` operators can be used if the operands are literals that are known at compile time. For example:\n\n```\ntemplate\u003cp1\u003e\n#define macro FOO = takes(0) returns(0) {\n    \u003cp1\u003e swap pop 0x01 mulmod\n}\n\n#define macro FOO_SIZE = takes(0) returns(0) {\n    __codesize(FOO\u003c0x01\u003e)\n}\n\n#define macro P = takes(0) returns(0) {\n    0x20\n}\n\n#define macro BAR = takes(0) returns(0) {\n    FOO\u003cFOO_SIZE+P\u003e()     // valid Huff code\n    FOO\u003c0x10*FOO_SIZE\u003e()  // valid Huff code\n    FOO\u003cFOO+0x10\u003e()       // invalid Huff code\n}\n```\n\nLiterals can be expressed in either decimal form or hexadecimal form (prepended by `0x`).  \n`push` opcodes are not used in Huff - literals used directly inside Huff code will be replaced with the smallest suitable `push` instruction by the compiler.\n\n### **\"Where can I find example Huff code?\"**\n\n[weierstrudel](https://github.com/AztecProtocol/weierstrudel/tree/master/huff_modules) is an elliptic curve arithmetic library written entirely in Huff, with its contract code totalling over 14kb.\n\n### **\"...Why is it called Huff?\"**\n\nHuff is a game played on a chess-board. One player has chess pieces, the other draughts pieces. The rules don't make any sense, the game is deliberately confusing and it is an almost mathematical certainty that the draughts player will lose. You won't find any reference to it online, because it was `invented' in a pub by some colleagues of mine in a past career and promptly forgotten about for being a terrible game.\n\nI found that writing Huff macros invoked similar emotions to playing Huff, hence the name.\n\n### **\"Despite everything I've just read I have a compelling desire to use Huff...can I contribute?\"**\n\nPlease, by all means. Huff is open-source and licensed under LGPL-3.0.\n\n### **Usage**\n\n```js\nconst { Runtime } = require('huff');\n\nconst main = new Runtime('main_loop.huff', 'path_to_macros');\nconst calldata = [\n    // calldata for macro\n    { index: 0, value: new BN(1) },\n    { index: 32, value: new BN(2) },\n];\nconst initialMemory = [\n    // intial memory state expected by macro\n    { index: 0, value: new BN(1234134) },\n    { index: 32, value: new BN(29384729832) },\n];\nconst inputStack = [new BN(1), new BN(6)]; // initial stack state expected by macro\nconst callvalue = 1; // amount of wei in transaction\nconst { stack, memory, gas, bytecode, returnData } = await main('MACRO_NAME', initialStack, initialMemory, calldata, callvalue);\n\nconsole.log('gas cost when executing macro = ', gas);\nconsole.log('macro bytecode = ', bytecode);\nconsole.log('macro return data = ', returnData);\nconsole.log('output stack state = ', stack);\nconsole.log('output memory state = ', memory);\n```\n\n### **Testing**\n\nTests can be run with `yarn test`. Example contracts, such as the ERC20 implementation, can be tested with `yarn exampletest`.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faztecprotocol%2Fhuff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faztecprotocol%2Fhuff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faztecprotocol%2Fhuff/lists"}