npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@anastasia-labs/smart-handles-offchain

v0.3.4

Published

https://docs.github.com/en/packages/quickstart

Downloads

253

Readme

Table of Contents

Off-Chain SDK for Smart Handles

Off-chain SDK for Smart Handles, offering configuration datatypes with corresponding transaction builders for all possible endpoints.

Endpoints

All endpoints provide 2 functions for 2 targets: single and batch. The script CBOR single targets require are fully applied spending scripts, while batch variants expect the CBOR to be that of a fully applied staking script.

The staking script's CBOR is internally applied to the included generic batch spending script in order to yield the batch spending script of the instance.

Fetch Requests

Given a LucidEvolution object and target script, the two offered functions query UTxOs sitting at their corresponding spending addresses.

Request

Functions for submitting simple and/or advanced requests to the instance:

RouteRequest is a sum type with 2 constructors, one for the simple requests, and one for the advanced ones:

export type TSRequiredMint = {
  policyId: PolicyId;
  tokenName: string;
};

export type SimpleRouteRequest = {
  valueToLock: Assets;
};

export type AdvancedRouteRequest = SimpleRouteRequest & {
  owner?: Address;
  routerFee: bigint;
  reclaimRouterFee: bigint;
  routeRequiredMint: TSRequiredMint | null;
  reclaimRequiredMint: TSRequiredMint | null;
  extraInfoDataBuilder: () => DatumJson;
};

export type RouteRequest =
  | { kind: "simple"; data: SimpleRouteRequest }
  | { kind: "advanced"; data: AdvancedRouteRequest };

Single and batch config datatypes are the following:

export type SingleRequestConfig = {
  scriptCBOR: CBORHex;
  routeRequest: RouteRequest;
  additionalRequiredLovelaces: bigint;
};

export type BatchRequestConfig = {
  stakingScriptCBOR: CBORHex;
  routeRequests: RouteRequest[];
  additionalRequiredLovelaces: bigint;
};

additionalRequiredLovelaces allow you to provide more safety by preventing request submissions that can lead to the funds getting permanently locked.

Simple Reclaim

Reclaiming a simple request only requires the signature of its owner.

Advanced reclaim is very similar to an advanced route, and therefore is expanded upon in the next section.

Routing & Advanced Reclaim

Before going over the configs themselves, let's look at some other common interfaces:

Simple & Advanced Output Datum Makers

Both of these endpoints need to provide a function that, given input assets and datum, returns the datum that should be attached to the produced UTxO at route address:

export type SimpleOutputDatumMaker = (
  inputAssets: Assets,
  inputDatum: SimpleDatumFields
) => Promise<Result<OutputDatum>>;

export type AdvancedOutputDatumMaker = (
  inputAssets: Assets,
  inputDatum: AdvancedDatumFields
) => Promise<Result<OutputDatum>>;

As a route transaction can be consuming a simple datum, route config may be provided with both of these datum makers.

Note the output type, Promise<Result<OutputDatum>>, allows your function to be both asynchronous, and fail-able with an error message.

Required Mint Config

Advanced requests can require mints/burns of a single asset for both route and reclaim. The datatype to model this is:

export type RequiredMintConfig = {
  mintQuantityFinder: (
    inputAssets: Assets,
    inputDatum: AdvancedDatumFields
  ) => Promise<Result<bigint>>;
  mintRedeemer: string;
  mintScript: Script;
};

Since the quantity of mint/burn can depend on the spent UTxO, a function similar to the output datum finder has to be provided. The other two should be fairly clear.

Additional Action

The underlying logic of an instance may have some extra requirements that smart handles wrapper does not provide. This function offers instance's off-chain to perform additional actions on a partially built transaction before passing it to be signed (e.g. including witness of an additional staking script):

export type AdditionalAction =
  (tx: TxBuilder, utxo: UTxO) => Promise<Result<TxBuilder>>;

Common Fields

export type CommonSingle = {
  scriptCBOR: CBORHex;
  requestOutRef: OutRef;
};

export type CommonBatch = {
  stakingScriptCBOR: CBORHex;
  requestOutRefs: OutRef[];
};

With these datatypes out of the way, we can now look at the advanced reclaim and route configs:

Advanced Reclaim Configs

export type AdvancedReclaimConfig = {
  outputDatumMaker: AdvancedOutputDatumMaker;
  requiredMintConfig?: RequiredMintConfig;
  additionalAction: AdditionalAction;
};

export type SingleReclaimConfig = CommonSingle & {
  advancedReclaimConfig?: AdvancedReclaimConfig;
};

export type BatchReclaimConfig = CommonBatch & {
  advancedReclaimConfig?: AdvancedReclaimConfig;
};

Route Configs

First we have route configs for simple and advanced requests:

export type SimpleRouteConfig = {
  additionalAction: AdditionalAction;
  outputDatumMaker: SimpleOutputDatumMaker;
};

export type AdvancedRouteConfig = {
  outputDatumMaker: AdvancedOutputDatumMaker;
  requiredMintConfig?: RequiredMintConfig;
  additionalAction: AdditionalAction;
};

And use them to define single and batch route configs:

export type SingleRouteConfig = CommonSingle & {
  routeAddress: Address;
  simpleRouteConfig?: SimpleRouteConfig;
  advancedRouteConfig?: AdvancedRouteConfig;
};

export type BatchRouteConfig = CommonBatch & {
  routeAddress: Address;
  simpleRouteConfig?: SimpleRouteConfig;
  advancedRouteConfig?: AdvancedRouteConfig;
};

Example

The example folder contains a project that not only uses this package, but also smart-handles-agent to implement a full off-chain solution for its on-chain counterpart.

The bulk of the implementation resides at minswap-v1.ts.

Additionally, there are also two preprod scenarios implemented at ./example/src/scenarios/ which should give you a more practical usage of this SDK.

Its sample transactions on preprod are linked in the example's README.md.