Package: hebi
hebiYou are building what you want. Why not also buildhowyou want?This is an implementation of smart contracts for Cardano which are written in a very strict subset of valid Python.
The general philosophy of this project is to write a compiler that
ensure the following:If the program compiles then:it is a valid Python programthe output running it with python is the same as running it on-chain.Note this is the sister project ofeopsin.
It uses an even more restricted subset of python (for example no while loops).
The benefit is that the resulting code is greatly reduced in size and cpu/memory consumption.Why hebi?100% valid Python. Leverage the existing tool stack for Python, syntax highlighting, linting, debugging, unit-testing,property-based testing,verificationIntuitive. Just like Python.Functional. Forces you to write elegant, functional code in Python.Efficient & Secure. Static type inference ensures strict typing and optimized codeEopsin is more comfortable to use than hebi.
If you want to start building, write your contract in eopsin first.
Then, after everything works to your pleasing, try to port to hebi and enjoy the performance gains.Getting StartedOpShin Pioneer ProgramCheck out theopshin-pioneer-programfor a host of educational example contracts, test cases and off-chain code.Example repositoryCheck out theopshin-starter-kitrepository for a quick start in setting up a development environment
and compiling some sample contracts yourself.You can replace the contracts in your local copy of the repository with code from theexamplessection here to start exploring different contracts.Developer Community and QuestionsThe eopsin repository contains a discussions page.
Feel free to open up a new discussion with questions regarding development using hebi and using certain features.
Others may be able to help you and will also benefit from the previously shared questions.Check out the communityhereYou can also chat with other developersin the welcoming discord
communityof OpShinInstallationInstall Python 3.8, 3.9 or 3.10. Then runpython3-mpipinstallhebiWriting a Smart ContractA short non-complete introduction in starting to write smart contracts follows.Make sure you understand EUTxOs, Addresses, Validators etc on Cardano.There is a wonderful crashcourse by @KtorZ. The contract will work on these conceptsMake sure you understand python. hebi works like python and uses python. There are tons of tutorials for python, choose what suits you best.Make sure your contract is valid python and the types check out. Write simple contracts first and run them usinghebi evalto get a feeling for how they work.Make sure your contract is valid hebi code. Runhebi compileand look at the compiler erros for guidance along what works and doesn't work and why.Dig into theexamplesto understand common patterns. Check out thepreludefor understanding how the Script Context is structured and how complex datums are defined.Check out thesample repositoryto find a sample setup for developing your own contract.In summary, a smart contract in hebi is defined by the functionvalidatorin your contract file.
The function validates that a specific value can be spent, minted, burned, withdrawn etc, depending
on where it is invoked/used as a credential.
If the function fails (i.e. raises an error of any kind such as aKeyErrororAssertionError)
the validation is denied, and the funds can not be spent, minted, burned etc.There is a subtle difference here in comparison to most other Smart Contract languages.
In hebi a validator may return anything (in particular alsoFalse) - as long as it does not fail, the execution is considered valid.
This is more similar to how contracts in Solidity always pass, unless they run out of gas or hit an error.
So make sure toassertwhat you want to ensure to hold for validation!A simple contract called the "Gift Contract" verifies that only specific wallets can withdraw money.
They are authenticated by a signature.
If you don't understand what a pubkeyhash is and how this validates anything, check outthis gentle introduction into Cardanos EUTxO.
Also see thetutorial bypycardanofor explanations on what each of the parameters to the validator means
and how to build transactions with the contract.fromhebi.preludeimport*@dataclassclassWithdrawDatum(PlutusData):pubkeyhash:bytesdefvalidator(datum:WithdrawDatum,redeemer:None,context:ScriptContext)->None:assertdatum.pubkeyhashincontext.tx_info.signatories,"Required signature missing"All contracts written in hebi are 100% valid python.
Minting policies expect only a redeemer and script context as argument.
Check out theArchitecture guidefor details on how to write double functioning contracts.
Theexamplesfolder contains more examples.
Also check out theopshin-pioneer-programandopshin-starter-kitrepo.CompilingWrite your program in python. You may start with the content ofexamples.
Arguments to scripts are passed in as Plutus Data objects in JSON notation.You can run any of the following commands# Evaluate script in Python - this can be used to make sure there are no obvious errorshebievalexamples/smart_contracts/assert_sum.py"{\"int\": 4}""{\"int\": 38}""{\"constructor\": 0, \"fields\": []}"# Compile script to 'uplc', the Cardano Smart Contract assemblyhebicompileexamples/smart_contracts/assert_sum.pyDeployingThe deploy process generates all artifacts required for usage with common libraries likepycardano,lucidand thecardano-cli.# Automatically generate all artifacts needed for using this contracthebibuildexamples/smart_contracts/assert_sum.pySee thetutorial bypycardanofor explanations how to build transactions withopshincontracts.The small printNot every valid python program is a valid smart contract.
Not all language features of python will or can be supported.
The reasons are mainly of practical nature (i.e. we can't infer types when functions likeevalare allowed).
Specifically, only a pure subset of python is allowed.
Further, only immutable objects may be generated.For your program to be accepted, make sure to only make use of language constructs supported by the compiler.
You will be notified of which constructs are not supported when trying to compile.NameHebi is japanese for "snake", which is a play on words onpython, the underlying language.Versioning schemeSince this project builds on top of eopsin, it has a particular versioning scheme.
The first three numbers indicate the version ofhebi(starting at0.1.0).
Then follows the latest version number ofeopsinwhich was merged into the project (starting at0.9.3).
This is intended to help navigating releases among both packages, where it might be important
that a recent eopsin release is integrated that contains a security patch.ContributingArchitectureThis program consists of a few independent components:An aggressive static type inferencerRewriting tools to simplify complex python expressionsA compiler from a subset of python into UPLCDebugging artefactsFor debugging purposes, you can also run# Compile script to 'uplc', and evaluate the script in UPLC (for debugging purposes)python3-mhebieval_uplcexamples/smart_contracts/assert_sum.py"{\"int\": 4}""{\"int\": 38}""{\"constructor\": 0, \"fields\": []}"# Compile script to 'pluto', an intermediate language (for debugging purposes)python3-mhebicompile_plutoexamples/smart_contracts/assert_sum.pySponsoringYou can sponsor the development of hebi through GitHub orTeikior just by sending ADA. Drop me a message on social media and let me know what it is for.KreateStake your ada to support OpShin atKreateGitHubSponsor the developers of this project through the button "Sponsor" next to themADADonation in ADA can be submitted to$opshinoraddr1qyz3vgd5xxevjy2rvqevz9n7n7dney8n6hqggp23479fm6vwpj9clsvsf85cd4xc59zjztr5zwpummwckmzr2myjwjns74lhmr.SupportersThe main sponsor of this project isInversion. Here is a word from them!At Inversion, we pride ourselves on our passion for life and our ability to create exceptional software solutions for our clients. Our team of experts, with over a century of cumulative experience, is dedicated to harnessing the power of the Cardano blockchain to bring innovative and scalable decentralized applications to life. We've successfully built applications for NFT management, staking and delegation, chain data monitoring, analytics, and web3 integrations, as well as countless non-blockchain systems. With a focus on security, transparency, and sustainability, our team is excited to contribute to the Cardano ecosystem, pushing the boundaries of decentralized technologies to improve lives worldwide. Trust Inversion to be your go-to partner for robust, effective, and forward-thinking solutions, whether blockchain based, traditional systems, or a mix of the two.They have recently started a podcast, called "Africa On Chain", which you can check out here:https://www.youtube.com/@africaonchain