From fa9899a623689a53115c184ee146951576495153 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niels=20M=C3=BCndler?= Date: Thu, 8 Feb 2024 22:28:22 +0100 Subject: [PATCH] Shorten the readme and refer more to the book --- README.md | 109 ++--------------------------------------- docs/index.js | 2 +- docs/opshin/index.html | 91 ++-------------------------------- 3 files changed, 7 insertions(+), 195 deletions(-) diff --git a/README.md b/README.md index a7ddb870..57db3b3d 100644 --- a/README.md +++ b/README.md @@ -33,33 +33,8 @@ If the program compiles then: ### Getting Started -#### OpShin Pioneer Program - -Check out the [opshin-pioneer-program]( -https://github.com/OpShin/opshin-pioneer-program) for a host of educational example contracts, test cases and off-chain code. - -#### Example repository - -Check out the [opshin-starter-kit]( -https://github.com/OpShin/opshin-starter-kit) repository 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 the -`examples` section here to start exploring different contracts. - -#### Developer Community and Questions - -This repository contains a discussions page. -Feel free to open up a new discussion with questions regarding development using opshin and using certain features. -Others may be able to help you and will also benefit from the previously shared questions. - -Check out the community [here](https://github.com/OpShin/opshin/discussions) - -You can also chat with other developers [in the welcoming discord -community](https://discord.gg/umR3A2g4uw) of OpShin - -> Help us improve OpShin by [participating in this survey!](https://forms.gle/KdzYYeeiWCwMTHsX9) +Check out the [OpShin Book](https://book.opshin.dev) for an introduction to this tool and details into writing smart contracts. +This document will just outline the basic usage of the tool. #### Installation @@ -71,59 +46,7 @@ python3 -m pip install opshin #### Writing a Smart Contract -A short non-complete introduction in starting to write smart contracts follows. - -1. Make sure you understand EUTxOs, Addresses, Validators etc on Cardano. [There is a wonderful crashcourse by @KtorZ](https://aiken-lang.org/fundamentals/eutxo). The contract will work on these concepts -2. Make sure you understand python. opshin works like python and uses python. There are tons of tutorials for python, choose what suits you best. -3. Make sure your contract is valid python and the types check out. Write simple contracts first and run them using `opshin eval` to get a feeling for how they work. -4. Make sure your contract is valid opshin code. Run `opshin compile` and look at the compiler erros for guidance along what works and doesn't work and why. -5. Dig into the [`examples`](https://github.com/OpShin/opshin/tree/main/examples) to understand common patterns. Check out the [`prelude`](https://opshin.opshin.dev/opshin/prelude.html) for understanding how the Script Context is structured and how complex datums are defined. -6. Check out the [sample repository](https://github.com/OpShin/opshin-starter-kit) to find a sample setup for developing your own contract. - - -In summary, a smart contract in opshin is defined by the function `validator` in 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 a `KeyError` or `AssertionError`) -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 opshin a validator may return anything (in particular also `False`) - 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 to `assert` what 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 out [this gentle introduction into Cardanos EUTxO](https://aiken-lang.org/fundamentals/eutxo). -Also see the [tutorial by `pycardano`](https://pycardano.readthedocs.io/en/latest/guides/plutus.html) for explanations on what each of the parameters to the validator means -and how to build transactions with the contract. - -```python3 -from opshin.prelude import * - - -@dataclass() -class WithdrawDatum(PlutusData): - pubkeyhash: bytes - - -def validator(datum: WithdrawDatum, redeemer: None, context: ScriptContext) -> None: - sig_present = False - for s in context.tx_info.signatories: - if datum.pubkeyhash == s: - sig_present = True - assert sig_present, "Required signature missing" -``` - -All contracts written in opshin are 100% valid python. -Minting policies expect only a redeemer and script context as argument. -Check out the [Architecture guide](https://github.com/OpShin/opshin/blob/main/ARCHITECTURE.md#minting-policy---spending-validator-double-function) -for details on how to write double functioning contracts. -The [`examples`](https://github.com/OpShin/opshin/blob/main/examples) folder contains more examples. -Also check out the [opshin-pioneer-program]( -https://github.com/OpShin/opshin-pioneer-program) - and [opshin-starter-kit]( -https://github.com/OpShin/opshin-starter-kit) repo. +Check out the [OpShin Book](https://book.opshin.dev) for an introduction to this tool and details into writing smart contracts. ### Compiling @@ -186,32 +109,6 @@ contract_addr = contract.mainnet_addr contract_blueprint = contract.blueprint ``` -### The small print - -_Not 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 like `eval` are 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. - -You can also make use of the built-in linting command and check it for example with the following command: - -```bash -opshin lint spending examples/smart_contracts/assert_sum.py -``` - -### Name - -> Eopsin (Korean: 업신; Hanja: 業神) is the goddess of the storage and wealth in Korean mythology and shamanism. -> [...] Eopsin was believed to be a pitch-black snake that had ears. [[1]](https://en.wikipedia.org/wiki/Eopsin) - -Since this project tries to merge Python (a large serpent) and Pluto/Plutus (Greek wealth gods), the name appears fitting. -The name e_opsin is pronounced _op-shin_. -e - ### Debugging artefacts For debugging purposes, you can also run diff --git a/docs/index.js b/docs/index.js index 1153a261..a11cdaa1 100644 --- a/docs/index.js +++ b/docs/index.js @@ -67,7 +67,7 @@ INDEX=[ { "ref":"opshin", "url":0, -"doc":" opshin > You are building what you want. Why not also build how you want? This is an implementation of smart contracts for Cardano which are written in a 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: 1. it is a valid Python program 2. the output running it with python is the same as running it on-chain. Why opshin? - 100% valid Python. Leverage the existing tool stack for Python, syntax highlighting, linting, debugging, unit-testing, [property-based testing](https: hypothesis.readthedocs.io/), [verification](https: github.com/marcoeilers/nagini) - Intuitive. Just like Python. - Flexible. Imperative, functional, the way you want it. - Efficient & Secure. Static type inference ensures strict typing and optimized code Getting Started OpShin Pioneer Program Check out the [opshin-pioneer-program]( https: github.com/OpShin/opshin-pioneer-program) for a host of educational example contracts, test cases and off-chain code. Example repository Check out the [opshin-starter-kit]( https: github.com/OpShin/opshin-starter-kit) repository 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 the examples section here to start exploring different contracts. Developer Community and Questions This repository contains a discussions page. Feel free to open up a new discussion with questions regarding development using opshin and using certain features. Others may be able to help you and will also benefit from the previously shared questions. Check out the community [here](https: github.com/OpShin/opshin/discussions) You can also chat with other developers [in the welcoming discord community](https: discord.gg/umR3A2g4uw) of OpShin > Help us improve OpShin by [participating in this survey!](https: forms.gle/KdzYYeeiWCwMTHsX9) Installation Install Python 3.8, 3.9, 3.10 or 3.11. Then run python3 -m pip install opshin Writing a Smart Contract A short non-complete introduction in starting to write smart contracts follows. 1. Make sure you understand EUTxOs, Addresses, Validators etc on Cardano. [There is a wonderful crashcourse by @KtorZ](https: aiken-lang.org/fundamentals/eutxo). The contract will work on these concepts 2. Make sure you understand python. opshin works like python and uses python. There are tons of tutorials for python, choose what suits you best. 3. Make sure your contract is valid python and the types check out. Write simple contracts first and run them using opshin eval to get a feeling for how they work. 4. Make sure your contract is valid opshin code. Run opshin compile and look at the compiler erros for guidance along what works and doesn't work and why. 5. Dig into the [ examples ](https: github.com/OpShin/opshin/tree/main/examples) to understand common patterns. Check out the [ prelude ](https: opshin.opshin.dev/opshin/prelude.html) for understanding how the Script Context is structured and how complex datums are defined. 6. Check out the [sample repository](https: github.com/OpShin/opshin-starter-kit) to find a sample setup for developing your own contract. In summary, a smart contract in opshin is defined by the function validator in 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 a KeyError or AssertionError ) 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 opshin a validator may return anything (in particular also False ) - 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 to assert what 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 out [this gentle introduction into Cardanos EUTxO](https: aiken-lang.org/fundamentals/eutxo). Also see the [tutorial by pycardano ](https: pycardano.readthedocs.io/en/latest/guides/plutus.html) for explanations on what each of the parameters to the validator means and how to build transactions with the contract. from opshin.prelude import @dataclass() class WithdrawDatum(PlutusData): pubkeyhash: bytes def validator(datum: WithdrawDatum, redeemer: None, context: ScriptContext) -> None: sig_present = False for s in context.tx_info.signatories: if datum.pubkeyhash s: sig_present = True assert sig_present, \"Required signature missing\" All contracts written in opshin are 100% valid python. Minting policies expect only a redeemer and script context as argument. Check out the [Architecture guide](https: github.com/OpShin/opshin/blob/main/ARCHITECTURE.md minting-policy -spending-validator-double-function) for details on how to write double functioning contracts. The [ examples ](https: github.com/OpShin/opshin/blob/main/examples) folder contains more examples. Also check out the [opshin-pioneer-program]( https: github.com/OpShin/opshin-pioneer-program) and [opshin-starter-kit]( https: github.com/OpShin/opshin-starter-kit) repo. Compiling Write your program in python. You may start with the content of examples . 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 errors opshin eval spending examples/smart_contracts/assert_sum.py \"{\\\"int\\\": 4}\" \"{\\\"int\\\": 38}\" d8799fd8799f9fd8799fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffd8799fd8799fd87a9f581cdbe769758f26efb21f008dc097bb194cffc622acc37fcefc5372eee3ffd87a80ffa140a1401a00989680d87a9f5820dfab81872ce2bbe6ee5af9bbfee4047f91c1f57db5e30da727d5fef1e7f02f4dffd87a80ffffff809fd8799fd8799fd8799f581cdc315c289fee4484eda07038393f21dc4e572aff292d7926018725c2ffd87a80ffa140a14000d87980d87a80ffffa140a14000a140a1400080a0d8799fd8799fd87980d87a80ffd8799fd87b80d87a80ffff80a1d87a9fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffffd87980a15820dfab81872ce2bbe6ee5af9bbfee4047f91c1f57db5e30da727d5fef1e7f02f4dd8799f581cdc315c289fee4484eda07038393f21dc4e572aff292d7926018725c2ffd8799f5820746957f0eb57f2b11119684e611a98f373afea93473fefbb7632d579af2f6259ffffd87a9fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffffff Compile script to 'uplc', the Cardano Smart Contract assembly opshin compile spending examples/smart_contracts/assert_sum.py Furthermore, you can add a shebang to the first line of the python file to indicate that it represents an opshin smart contract. You can choose from the following options: - a general shebang: !opshin , which represents opshin eval any - or a more specific purpose: !/usr/bin/env -S opshin eval minting By doing so, you can transform your python file to an executable: chmod +x your_file.py and execute it with ./your_file.py , which will run opshin eval any ./your_file.py under the hood. Deploying The deploy process generates all artifacts required for usage with common libraries like [pycardano](https: github.com/Python-Cardano/pycardano), [lucid](https: github.com/spacebudz/lucid) and the [cardano-cli](https: github.com/input-output-hk/cardano-node). Automatically generate all artifacts needed for using this contract opshin build spending examples/smart_contracts/assert_sum.py See the [tutorial by pycardano ](https: pycardano.readthedocs.io/en/latest/guides/plutus.html) for explanations how to build transactions with opshin contracts. API for Smart Contracts The python interface offers a simple API to compile, load, apply parameters and evaluate smart contracts. from opshin.builder import Build a validator script from a python file that contains a validator function contract = build(\"path/to/contract.py\") You can apply parameters to the contract during compilation contract = build(\"path/to/contract.py\", arg1, arg2, arg3) Store the compilation artifacts in a folder contract.dump(\"path/to/store\") You can also load a compiled contract from a path contract = load(\"path/to/store\") And apply parameters after loading a contract contract = contract.apply_parameters(arg1, arg2, arg3) The artifacts contain the compiled script, the policy ID and the addresses and blueprint contract_addr = contract.mainnet_addr contract_blueprint = contract.blueprint The small print _Not 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 like eval are 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. You can also make use of the built-in linting command and check it for example with the following command: opshin lint spending examples/smart_contracts/assert_sum.py Name > Eopsin (Korean: \uc5c5\uc2e0; Hanja: \u696d\u795e) is the goddess of the storage and wealth in Korean mythology and shamanism. > [ .] Eopsin was believed to be a pitch-black snake that had ears. 1 (https: en.wikipedia.org/wiki/Eopsin) Since this project tries to merge Python (a large serpent) and Pluto/Plutus (Greek wealth gods), the name appears fitting. The name e_opsin is pronounced _op-shin_. e Debugging artefacts For debugging purposes, you can also run Compile script to 'uplc', and evaluate the script in UPLC (for debugging purposes) opshin eval_uplc spending examples/smart_contracts/assert_sum.py \"{\\\"int\\\": 4}\" \"{\\\"int\\\": 38}\" d8799fd8799f9fd8799fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffd8799fd8799fd87a9f581cdbe769758f26efb21f008dc097bb194cffc622acc37fcefc5372eee3ffd87a80ffa140a1401a00989680d87a9f5820dfab81872ce2bbe6ee5af9bbfee4047f91c1f57db5e30da727d5fef1e7f02f4dffd87a80ffffff809fd8799fd8799fd8799f581cdc315c289fee4484eda07038393f21dc4e572aff292d7926018725c2ffd87a80ffa140a14000d87980d87a80ffffa140a14000a140a1400080a0d8799fd8799fd87980d87a80ffd8799fd87b80d87a80ffff80a1d87a9fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffffd87980a15820dfab81872ce2bbe6ee5af9bbfee4047f91c1f57db5e30da727d5fef1e7f02f4dd8799f581cdc315c289fee4484eda07038393f21dc4e572aff292d7926018725c2ffd8799f5820746957f0eb57f2b11119684e611a98f373afea93473fefbb7632d579af2f6259ffffd87a9fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffffff Compile script to 'pluto', an intermediate language (for debugging purposes) opshin compile_pluto spending examples/smart_contracts/assert_sum.py Contributing Developing and Technical Documentation Generally, all contributions on the code side are very welcome. To get an overview over the architecture and idea behind OpShin, check out [the Technical Documentation](./ARCHITECTURE.md). Sponsoring You can sponsor the development of opshin through GitHub or [Patreon](https: patreon.com/OpShin) or just by sending ADA. Drop me a message on social media and let me know what it is for. - Patreon Support OpShin at [Patreon](https: patreon.com/OpShin) to enjoy member benefits! - GitHub Sponsor the developers of this project through the button \"Sponsor\" next to them - ADA Donation in ADA can be submitted to $opshin or addr1qyz3vgd5xxevjy2rvqevz9n7n7dney8n6hqggp23479fm6vwpj9clsvsf85cd4xc59zjztr5zwpummwckmzr2myjwjns74lhmr . Supporters The main sponsor of this project is [Inversion](https: inversion.dev/cardano/). 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" +"doc":" opshin > You are building what you want. Why not also build how you want? This is an implementation of smart contracts for Cardano which are written in a 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: 1. it is a valid Python program 2. the output running it with python is the same as running it on-chain. Why opshin? - 100% valid Python. Leverage the existing tool stack for Python, syntax highlighting, linting, debugging, unit-testing, [property-based testing](https: hypothesis.readthedocs.io/), [verification](https: github.com/marcoeilers/nagini) - Intuitive. Just like Python. - Flexible. Imperative, functional, the way you want it. - Efficient & Secure. Static type inference ensures strict typing and optimized code Getting Started Check out the [OpShin Book](https: book.opshin.dev) for an introduction to this tool and details into writing smart contracts. This document will just outline the basic usage of the tool. Installation Install Python 3.8, 3.9, 3.10 or 3.11. Then run python3 -m pip install opshin Writing a Smart Contract Check out the [OpShin Book](https: book.opshin.dev) for an introduction to this tool and details into writing smart contracts. Compiling Write your program in python. You may start with the content of examples . 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 errors opshin eval spending examples/smart_contracts/assert_sum.py \"{\\\"int\\\": 4}\" \"{\\\"int\\\": 38}\" d8799fd8799f9fd8799fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffd8799fd8799fd87a9f581cdbe769758f26efb21f008dc097bb194cffc622acc37fcefc5372eee3ffd87a80ffa140a1401a00989680d87a9f5820dfab81872ce2bbe6ee5af9bbfee4047f91c1f57db5e30da727d5fef1e7f02f4dffd87a80ffffff809fd8799fd8799fd8799f581cdc315c289fee4484eda07038393f21dc4e572aff292d7926018725c2ffd87a80ffa140a14000d87980d87a80ffffa140a14000a140a1400080a0d8799fd8799fd87980d87a80ffd8799fd87b80d87a80ffff80a1d87a9fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffffd87980a15820dfab81872ce2bbe6ee5af9bbfee4047f91c1f57db5e30da727d5fef1e7f02f4dd8799f581cdc315c289fee4484eda07038393f21dc4e572aff292d7926018725c2ffd8799f5820746957f0eb57f2b11119684e611a98f373afea93473fefbb7632d579af2f6259ffffd87a9fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffffff Compile script to 'uplc', the Cardano Smart Contract assembly opshin compile spending examples/smart_contracts/assert_sum.py Furthermore, you can add a shebang to the first line of the python file to indicate that it represents an opshin smart contract. You can choose from the following options: - a general shebang: !opshin , which represents opshin eval any - or a more specific purpose: !/usr/bin/env -S opshin eval minting By doing so, you can transform your python file to an executable: chmod +x your_file.py and execute it with ./your_file.py , which will run opshin eval any ./your_file.py under the hood. Deploying The deploy process generates all artifacts required for usage with common libraries like [pycardano](https: github.com/Python-Cardano/pycardano), [lucid](https: github.com/spacebudz/lucid) and the [cardano-cli](https: github.com/input-output-hk/cardano-node). Automatically generate all artifacts needed for using this contract opshin build spending examples/smart_contracts/assert_sum.py See the [tutorial by pycardano ](https: pycardano.readthedocs.io/en/latest/guides/plutus.html) for explanations how to build transactions with opshin contracts. API for Smart Contracts The python interface offers a simple API to compile, load, apply parameters and evaluate smart contracts. from opshin.builder import Build a validator script from a python file that contains a validator function contract = build(\"path/to/contract.py\") You can apply parameters to the contract during compilation contract = build(\"path/to/contract.py\", arg1, arg2, arg3) Store the compilation artifacts in a folder contract.dump(\"path/to/store\") You can also load a compiled contract from a path contract = load(\"path/to/store\") And apply parameters after loading a contract contract = contract.apply_parameters(arg1, arg2, arg3) The artifacts contain the compiled script, the policy ID and the addresses and blueprint contract_addr = contract.mainnet_addr contract_blueprint = contract.blueprint Debugging artefacts For debugging purposes, you can also run Compile script to 'uplc', and evaluate the script in UPLC (for debugging purposes) opshin eval_uplc spending examples/smart_contracts/assert_sum.py \"{\\\"int\\\": 4}\" \"{\\\"int\\\": 38}\" d8799fd8799f9fd8799fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffd8799fd8799fd87a9f581cdbe769758f26efb21f008dc097bb194cffc622acc37fcefc5372eee3ffd87a80ffa140a1401a00989680d87a9f5820dfab81872ce2bbe6ee5af9bbfee4047f91c1f57db5e30da727d5fef1e7f02f4dffd87a80ffffff809fd8799fd8799fd8799f581cdc315c289fee4484eda07038393f21dc4e572aff292d7926018725c2ffd87a80ffa140a14000d87980d87a80ffffa140a14000a140a1400080a0d8799fd8799fd87980d87a80ffd8799fd87b80d87a80ffff80a1d87a9fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffffd87980a15820dfab81872ce2bbe6ee5af9bbfee4047f91c1f57db5e30da727d5fef1e7f02f4dd8799f581cdc315c289fee4484eda07038393f21dc4e572aff292d7926018725c2ffd8799f5820746957f0eb57f2b11119684e611a98f373afea93473fefbb7632d579af2f6259ffffd87a9fd8799fd8799f582055d353acacaab6460b37ed0f0e3a1a0aabf056df4a7fa1e265d21149ccacc527ff01ffffff Compile script to 'pluto', an intermediate language (for debugging purposes) opshin compile_pluto spending examples/smart_contracts/assert_sum.py Contributing Developing and Technical Documentation Generally, all contributions on the code side are very welcome. To get an overview over the architecture and idea behind OpShin, check out [the Technical Documentation](./ARCHITECTURE.md). Sponsoring You can sponsor the development of opshin through GitHub or [Patreon](https: patreon.com/OpShin) or just by sending ADA. Drop me a message on social media and let me know what it is for. - Patreon Support OpShin at [Patreon](https: patreon.com/OpShin) to enjoy member benefits! - GitHub Sponsor the developers of this project through the button \"Sponsor\" next to them - ADA Donation in ADA can be submitted to $opshin or addr1qyz3vgd5xxevjy2rvqevz9n7n7dney8n6hqggp23479fm6vwpj9clsvsf85cd4xc59zjztr5zwpummwckmzr2myjwjns74lhmr . Supporters The main sponsor of this project is [Inversion](https: inversion.dev/cardano/). 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" }, { "ref":"opshin.bridge", diff --git a/docs/opshin/index.html b/docs/opshin/index.html index 13795c4a..b7f92ccb 100644 --- a/docs/opshin/index.html +++ b/docs/opshin/index.html @@ -94,75 +94,14 @@

Why opshin?

  • Efficient & Secure. Static type inference ensures strict typing and optimized code

    • Getting Started

    -

    OpShin Pioneer Program

    -

    Check out the opshin-pioneer-program for a host of educational example contracts, test cases and off-chain code.

    -

    Example repository

    -

    Check out the opshin-starter-kit repository 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 the -examples section here to start exploring different contracts.

    -

    Developer Community and Questions

    -

    This repository contains a discussions page. -Feel free to open up a new discussion with questions regarding development using opshin and using certain features. -Others may be able to help you and will also benefit from the previously shared questions.

    -

    Check out the community here

    -

    You can also chat with other developers in the welcoming discord -community of OpShin

    -
    -

    Help us improve OpShin by participating in this survey!

    -
    +

    Check out the OpShin Book for an introduction to this tool and details into writing smart contracts. +This document will just outline the basic usage of the tool.

    Installation

    Install Python 3.8, 3.9, 3.10 or 3.11. Then run

    python3 -m pip install opshin

    Writing a Smart Contract

    -

    A short non-complete introduction in starting to write smart contracts follows.

    -
      -
    1. Make sure you understand EUTxOs, Addresses, Validators etc on Cardano. There is a wonderful crashcourse by @KtorZ. The contract will work on these concepts
      2. -
    2. Make sure you understand python. opshin works like python and uses python. There are tons of tutorials for python, choose what suits you best.
      3. -
    3. Make sure your contract is valid python and the types check out. Write simple contracts first and run them using opshin eval to get a feeling for how they work.
      4. -
    4. Make sure your contract is valid opshin code. Run opshin compile and look at the compiler erros for guidance along what works and doesn't work and why.
      5. -
    5. Dig into the examples to understand common patterns. Check out the prelude for understanding how the Script Context is structured and how complex datums are defined.
      6. -
    6. Check out the sample repository to find a sample setup for developing your own contract.
      7. -
    -

    In summary, a smart contract in opshin is defined by the function validator in 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 a KeyError or AssertionError) -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 opshin a validator may return anything (in particular also False) - 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 to assert what 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 out this gentle introduction into Cardanos EUTxO. -Also see the tutorial by pycardano for explanations on what each of the parameters to the validator means -and how to build transactions with the contract.

    -
    from opshin.prelude import *
-
-
-@dataclass()
-class WithdrawDatum(PlutusData):
-    pubkeyhash: bytes
-
-
-def validator(datum: WithdrawDatum, redeemer: None, context: ScriptContext) -> None:
-    sig_present = False
-    for s in context.tx_info.signatories:
-        if datum.pubkeyhash == s:
-            sig_present = True
-    assert sig_present, "Required signature missing"
-
    -

    All contracts written in opshin are 100% valid python. -Minting policies expect only a redeemer and script context as argument. -Check out the Architecture guide -for details on how to write double functioning contracts. -The examples folder contains more examples. -Also check out the opshin-pioneer-program -and opshin-starter-kit repo.

    +

    Check out the OpShin Book for an introduction to this tool and details into writing smart contracts.

    Compiling

    Write your program in python. You may start with the content of examples. Arguments to scripts are passed in as Plutus Data objects in JSON notation.

    @@ -209,25 +148,6 @@

    API for Smart Contracts

    contract_addr = contract.mainnet_addr contract_blueprint = contract.blueprint -

    The small print

    -

    Not 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 like eval are 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.

    -

    You can also make use of the built-in linting command and check it for example with the following command:

    -
    opshin lint spending examples/smart_contracts/assert_sum.py
-
    -

    Name

    -
    -

    Eopsin (Korean: 업신; Hanja: 業神) is the goddess of the storage and wealth in Korean mythology and shamanism. -[…] Eopsin was believed to be a pitch-black snake that had ears. [1]

    -
    -

    Since this project tries to merge Python (a large serpent) and Pluto/Plutus (Greek wealth gods), the name appears fitting. -The name e_opsin is pronounced op-shin. -e

    Debugging artefacts

    For debugging purposes, you can also run

    # Compile script to 'uplc', and evaluate the script in UPLC (for debugging purposes)
@@ -419,9 +339,6 @@ 
    Index