Proposal: Taqueria Typescript Package - DSL for Advanced Deployments

[mweichert]

@taqueria/taqueria

Introduction

The @taqueria/taqueria package is more than just a toolkit—it's essentially a Domain-Specific Language (DSL) designed for Tezos smart contract development. By abstracting many of the technical details, it offers a clean and developer-friendly API.

Why Choose @taqueria/taqueria?

• DSL API: Designed with a DSL-like interface for a more intuitive developer experience.
• Flexibility & Control: Customize your development flow with Task Scripts.
• Extensible Plugin Architecture: Enhance Taqueria with custom actions, environment controls, compiler tools, and other utilities.

What Taqueria Abstracts

When you declare an instance using Taqueria.contract(), several actions and decisions are abstracted away:

1. Conditional Compilation: Your contract is compiled only if necessary, with the default behavior being compilation when changed.
2. Storage Initialization: Initial storage is set up based on the storage parameter.
3. Account Association: The Tezos account to use is specified through the account property in the config object.
4. Conditional Deployment: The contract is deployed conditionally, with the default being deployment if the contract isn't already deployed.
5. Logging: Taqueria logs each action it performs, keeping you informed.

Problem-Solvers

Code-Signing Issues

Just run npx taq and forget about code-signing issues.

Complex Deployments

Taqueria understands your project and environment, simplifying complex deployments.

Scalable Development

A unified testing approach ensures you don't have to support multiple frameworks.

Basic Usage

import Taqueria from '@taqueria/taqueria'

export default async function (config) {
  const Increment = await Taqueria.contract('increment.mligo', {
    storage: 100,
    account: config.account
  })

  await Increment.methods.inc()
  await Taqueria.assert(await Increment.storage() === 100)
}

Behind the Scenes with Taqueria.contract()

When you run this script, here's what Taqueria automatically does for you:

1. Conditional Compilation: Taqueria compiles the contract only if there have been changes since the last compile.
2. Storage Initialization: The initial value of storage is set to 100.
3. Account Association: The Tezos account specified in config.account is used for deploying the contract.
4. Conditional Deployment: If the contract hasn't been deployed yet, Taqueria takes care of it.
5. Logging: Every action, such as compilation or method invocation, is logged for your convenience.

Extending Taqueria with Plugins

• New Actions: Implement custom actions.
• Behaviors: Modify or extend existing behaviors.
• Environment Controls: Add or modify environment variables.
• Compiler Tools: Support for additional languages and compilers.
• Indexers: Make contract data searchable and easily accessible.

Terminology

• Task Scripts: Custom TypeScript files for specific actions.
• Function Returned by Script: Accepts a config object and serves as your main entry point.

Error Handling

Run into errors? No worries. Just catch them with standard try/catch/finally blocks.

[ricklove]

@mweichert This looks very clean!

I think this approach makes a lot of sense and would be useful for both deployments and testing.

It might be useful to add some more examples with a contrast to what the code would look like currently.

Some questions:

1. For conditional deployment, what happens if the initial storage value changes? I would expect it to either redeploy a new contract or show a warning that the initial storage had changed.
2. In a production scenario, I would want to control auto deploy and error if the contract address is not found (i.e. deploy only if the address is null, or similar). Is there a way to do that?

[mweichert]

@ricklove thanks for the feedback!

For conditional deployment, what happens if the initial storage value changes? I would expect it to either redeploy a new contract or show a warning that the initial storage had changed.

My thought was that a new contract would be deployed with the updated storage.

In a production scenario, I would want to control auto deploy and error if the contract address is not found (i.e. deploy only if the address is null, or similar). Is there a way to do that?

To be sure I understand, lets assume you had the following:

const Increment = await Taqueria.contract('increment.mligo', {
    storage: 100,
    account: config.account
  })

If the Taqueria internal state is missing a contract address for the Increment contract with the associated storage, rather than originate this automatically, you'd prefer an error to be thrown that you could try/catch yourself? If that's desirable, I think we could handle that by allowing you to specify options, such as 'autoDeploy' to false in your environment config. What do you think?

[mweichert]

I discovered this today: https://blockwatch.cc/blog/tzcompose-tezos-automation-framework/

We could explore whether it makes sense to develop a plugin around TzCompose.