plutonomicon/pluto

An untyped Plutus Core assembler

P L U T O N O M I C O N

Introduction

The Plutonomicon is a developer-driven guide to the Plutus smart contract language in practice.

Since this ecosystem is moving at a breakneck speed, we ask that ANY information posted that is not confirmed to work on chain be labelled as 🔧 work in progress.

Available resources

We currently provide the following resources, broadly organized by topic.

Fundamentals and explanations

• The Fundamentals of Plutus, which gives a brief introduction to the Plutus language.
• Plutus from a Transaction Perspective, which gives another perspective to the environment Plutus runs in.
• Plutus Numeric Hierarchy, which gives an overview of the Plutus numerical type class stack, as well as the extensions to it provided by plutus-numeric.
• User guide to plutus-numeric, which gives a more 'example-driven' explanation for how to do certain common tasks using plutus-numeric.
• How Stake Validators Actually Work, which gives an explanation of 'Stake Validators'.

Design patterns

• Forward Minting Policy. Also described in another writeup. Some caution is required, as you may not wish to directly reference a script to obtain a hash used to identify the two scripts, as this method details.
• Come and Go Proof Tokens
• State Thread Token Pattern
• DistributedMap, describing an on-chain implementation of key-value mappings. This is naive, and mostly designed for conceptual illustration.
• Consistency of a Distributed Map, which explains some ways of operating on a distributed map.
• Stick Breaking Set, describing an on-chain method of proving presence or absence in a set.
• On-Chain Association List With Constant Time Insert-Removal, describing a pattern that can be used to replicate account-style maps without breaking transaction size limits. This is the optimized version of the naive version of that data structure.
• Transaction Tokens provide an method of deferring validation to minting policies for the purpose of validating entire transactions rather than the unlocking of individual UTxOs.
  • The Transaction Token Pattern document introduces the pattern.
  • The Transaction Token Protocol Architecture document introduces a conceptual and practical framework leveraging the pattern for specifying and implementing protocols.
  • The Protocol Category Sketch document sketches a formalism to establish a formalism that places protocols described according the the Architecture into the language of symmetric monoidal categories, and works through some examples of how wiring diagrams and aid specification and implementation.

Testing and optimization

• Staying In Bounds, which describes the testing interface for Plutus on-chain size provided by plutus-size-check.

Script Optimization Techniques:

• Reducing Plutus Script Sizes
• Optimizations to reduce CPU and Mem consumption
• Shrinker (shrinker is currently unmaintained)

Plutus Vulnerabilities:

• Common Plutus Vulnerabilities

Discussion

To discuss the projects and the content under the Plutonomicon umbrella, join our Discord: https://discord.gg/722KnTC8jF

Running the website

If you'd like to run a live version of the website locally:

nix run

As you edit¹ and save the Markdown files, the browser view should update instantly without requiring a manual refresh. Run nix build to build the statically generated website. See Emanote guide for further information.

Please note the Markdown writing conventions:

• There must be zero or one level 1 heading (# A heading) as the first line.
  • If a level 1 heading is not specified, title will be derived from the filename.
• All other headings must be level 2 or greater.

Footnotes

1. Try Obsidian or VSCode with vscode-memo for editing. ↩

pluto's Issues

Access ScriptContext in Pluto validator

Use Constr and the like to drill-down into ScriptContext validator argument, and see what it takes to access the various (deeply nested) data in it.

Write a contract in Pluto, and property test it

Write a trivial validator in Pluto (not parsing ScriptContext yet) and then test it in Emulator Trace monad. Compare its behaviour to the equivalent validator in Haskell.

Then use Plutus.Contract.Test.ContractModel to property test both the contracts (Haskell and Pluto).

More examples please

A side-by-side example of Plutus output and an equivalent hand-written Pluto expression could go a long way to justify the project.

Grammer for `Map` and `List` is incorrect

The syntax grammer notes-

Data ::= "data" ( Sigma | List | Map | Integer | ByteString )

List ::= "[" Data* "]"

Map ::= "{" ( Data "=" Data )* "}"

Which suggests that { data 1 = data 5 } would be a valid Map, and [ data 1 ] would be a valid List. However, the parser doesn't actually expect the data keyword, it just expects the data literal.

If the parse behavior is intentional, then the grammer needs to be updated. If the grammer is correct, then the parse behavior should be updated.

`FromUPLC` (and preferably `ToPluto`) instance for `BuiltinData`

Returning BuiltinData (or Data) from a pluto program (built using pluto's data syntax) is probably the most common usecase for pluto functions. Hence, I think there should be a FromUPLC instance for BuiltinData. Or is there some other way to implement this use case?

Pluto typechecker (opinion)

Hi,

Thank you for creating/working on/sharing Pluto.

What are your thoughts on integrating a System F type-checker with the current Pluto implementation?(of course, with type erasure) Do you consider it a feasible/good idea?

Using operators without parens fails silently

1 +i 1 +i 1 evaluates to 2

Implement generator for prime fields

A function that takes in a prime number p and outputs the field operations on the finite field of order p. To clarify, we want an implementation in pluto, not as a builtin or anything.

Configurable binary output formats

Add a flag to pluto assemble which controls the format of the binary output. Offer the following options: hex, base64, raw binary.

`field-of-rationals.pluto` doesn't terminate

This runs forever,

cabal run pluto -- run examples/field-of-rationals.pluto

Run tests in CI

To run tests:

cabal run spec
cabal run pluto-sample-contract

See https://docs.hercules-ci.com/

Add a disassembler from UPLC to Pluto

The main benefit for an end-user would be the ability to run it on a Plutus output and then hand-optimize the resulting Pluto expression.

Also, it would open more avenues for testing: round-tripping a bunch of UPLC inputs through disassembler and parser/assembler should yield the original.

if...then doesn't work

if True then 1 else 0
pluto run ...

Error(eval): EvaluationException "An error has occurred:  error:\nA builtin received a term argument when something else was expected\nCaused by: (ifThenElse True)" "UnexpectedBuiltinTermArgumentMachineError"

"pluto/nixpkgs follows a non-existent input 'haskellNix/nixpkgs-unstable'" error upon adding pluto as flake input

For this basic flake file, just to add the pluto binary to the shell-

{
  description = "A very basic flake";

  inputs.pluto =  {
    type = "github";
    owner = "Plutonomicon";
    repo = "pluto";
    rev = "339c05396190ba09ad3ec4a3efd609ed1c4c21e0";
  };

  outputs = { self, nixpkgs, pluto }:
    let
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
    in {

      packages.x86_64-linux.hello = pkgs.hello;

      defaultPackage.x86_64-linux = self.packages.x86_64-linux.hello;

      devShell.x86_64-linux =
        pkgs.mkShell { buildInputs = [ self.packages.x86_64-linux.hello pluto.defaultPackage.x86_64-linux ]; };
    };
}

I get the error-

error: input 'pluto/nixpkgs' follows a non-existent input 'haskellNix/nixpkgs-unstable'

       … while updating the lock file of flake 'path:/...'

Interestingly, the error goes away if I'm not specifying the commit-

{
  description = "A very basic flake";

  inputs.pluto =  {
    type = "github";
    owner = "Plutonomicon";
    repo = "pluto";
  };

  outputs = { self, nixpkgs, pluto }:
    let
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
    in {

      packages.x86_64-linux.hello = pkgs.hello;

      defaultPackage.x86_64-linux = self.packages.x86_64-linux.hello;

      devShell.x86_64-linux =
        pkgs.mkShell { buildInputs = [ self.packages.x86_64-linux.hello pluto.defaultPackage.x86_64-linux ]; };
    };
}

This works fine.