Documentation

The never-applicable tweak.

The tweak that always applies and leaves the transaction unchanged.

The "tweak" that obtains some value from the TxSkel. This does *not* modify the transaction.

Like the viewTweak, but returns a list of all foci

The tweak that sets a certain value in the TxSkel.

The tweak that modifies a certain value in the TxSkel.

Like overTweak, but only modifies foci on which the argument function returns Just the new focus. Returns a list of the foci that were modified, as they were before the tweak, and in the order in which they occurred on the original transaction.

Sometimes overMaybeTweak modifies too many foci. This might be the case if there are several identical foci, but you only want to modify some of them. This is where this Tweak becomes useful: The (Integer -> Bool) argument can be used to select which of the modifiable foci should be actually modified.

overMaybeTweak requires a modification that can fail (targeting Maybe). Sometimes, it can prove more convenient to explicitly state which property the foci shoud satisfy to be eligible for a modification that cannot fail instead. selectP provides a prism to make such a selection. The intended use case is 'overTweak (optic % selectP prop) mod' where optic gives the candidate foci, prop is the predicate to be satisfied by the foci, and mod is the modification to be applied to the selected foci.

When constructing a tweak from an optic and a modification of foci, there are in principle two options for optics with many foci: (a) apply the modification to all foci and return one modified transaction (b) generate a number of transactions that contain different combinations of modified and un-modified foci.

While most of the other "optic -> tweak" functions in this module take take the route (a), this function enables strategy (b).

Explanation of the arguments and return value

• Each of the foci of the Optic k (WithIx is) TxSkel x argument is something in the transaction that we might want to modify.
• The is -> x -> m [(x, l)] argument computes a list of possible modifications for each focus, depending on its index. For each modified focus, it also returns a "label" of type l, which somehow describes the modification that was made.
• The [is] -> [[is]] argument determines which combinations of (un-) modified foci will be present on the modified transactions: The input is a list of all of the indices of foci, and for each element [i_1,...,i_n] of the output list, all possible modified transactions that have a modification applied to the foci with indices i_1,...,i_n are generated.
• The return value of type [l] is the list of labels of all modified foci, in the order in which their indices occurred. Later tweaks may use this list to decide what to do.

Example 1

Assume the optic has three foci, let's denote them by a, b, c :: x, with indices 1, 2, 3 :: Integer respectively. Also assume that the is -> x -> m [(x, l)] argument returns lists of 2, 3, and 5 elements on a, b, and c, respectively. Let's call those elements a1, a2 and b1, b2, b3 and c1, c2, c3, c4, c5.

If the [ix] -> [[ix]] argument is map (:[]), you will try every modification on a separate transaction, since

map (:[]) [1, 2, 3] = [[1], [2], [3]]  .

Thus, there'll be 2+3+5=10 modified transactions in our examples. Namely, for each element of the list

[a1, a2, b1, b2, b3, c1, c2, c3, c4, c5]

you'll get one modified transaction that includes that value in place of the original focus.

Example 2

In the setting of the first example, if you want to try combining all possible modifications of one focus with all possible modifications of all other foci, choose tail . subsequences for the @[ix] -> [[ix]] argument. We have

tail (subsequences [1, 2, 3])
  == [ [1], [2], [3],
       [1, 2], [1, 3], [2, 3],
       [1, 2, 3]
     ]

This will correspond to the following 71 modified transactions, represented by the list of modified foci they contain:

[ -- one modified focus (the 10 cases from Example 1)
  [a1],
  [a2],
  ...
  [c4],
  [c5],

  -- two modifications of different foci (2*3 + 2*5 + 3*5 = 31 cases)
  [a1, b1],
  [a1, b2],
  ...
  [b3, c4],
  [b3, c5],

  -- three modified foci, one from each focus (2*3*5 = 30 cases)
  [a1, b1, c1],
  [a1, b1, c2],
  ...
  [a1, b3, c4],
  [a1, b3, c5]
]

So you see that tweaks constructed like this can branch quite wildly. Use with caution!

Like viewTweak, only for indexed optics.

Ensure that a given TxOutRef is being spent with a given TxSkelRedeemer. The return value will be Just the added data, if anything changed.

Add an input to a transaction. If the given TxOutRef is already being consumed by the transaction, fail.

Remove transaction inputs according to a given predicate. The returned list contains all removed inputs.

Applies an optional modification to all spend redeemers of type a

Add a label to a TxSkel.

Removes a label from a TxSkel

Checks if a given label is present in the TxSkel

Add a new entry to the TxSkelMints of the transaction skeleton under modification. As this is implemented in terms of addToTxSkelMints, the same caveats apply as do to that function!

Remove some entries from the TxSkelMints of a transaction, according to some predicate. The returned list holds the removed entries.

Modify transactions by changing the ordering of output constraints. If the PermutTweakMode is

• KeepIdentity (Just n), the unmodified transaction is included in the list of modified transactions and only the first n outputs are permuted,
• KeepIdentity Nothing, the unmodified transaction is included and all outputs are permuted. Use this with care; there might be a lot of permutations!
• OmitIdentity (Just n), the unmodified transaction is not included in the list of modified transactions and only the first n outputs are permuted,
• OmitIdentity Nothing, the unmodified transaction is not included and all outputs are permuted. Use this with care; there might be a lot of permutations!

(In particular, this is clever enough to generate only the distinct permutations, even if some outputs are identical.)

This randomly permutes the outputs of a transaction with a given seed Can be used to assess if a certain validator is order-dependant

Ensure that a certain output is produced by a transaction. The return value will be Just the added output, when applicable.

Add a transaction output, at the end of the current list of outputs, thus retaining the initial outputs order.

Remove transaction outputs according to some predicate. The returned list contains all the removed outputs.

A tweak that tries to change the datum on outputs carrying datums of a certain type with a prescribed tampering function. The tampering function ignores datums of other types and those for which it returns Nothing.

The tweak returns a list of the modified datums, as they were *before* the modification was applied to them.

A tweak that tries to change the datum on outputs carrying datums of a certain type with a prescribed tampering function. There are two main differences with tamperDatumTweak. First, the tampering function returns BuiltinData, allowing it to do pretty much anything with the datums. Second, for every output datum there are zero or more options for how to modify it, and all combinations of these modifications are tried.

That is, if there are n output datums, for which there are 'k_1,...,k_n' possible modifications, this tweak will try

  k_1 + ... + k_n
+ k_1 * k_2 + ... + k_{n-1} * k_n
+ k_1 * k_2 * k_3 + ... + k_{n-2} * k_{n-1} * k_n
+ ...
+ k_1 * k_2 * ... * k_{n-1} * k_n
== (k_1 + 1) * ... * (k_n + 1) - 1

modified transactions.

Returns the current list of signers

Apply a function to the list of signers and return the old ones

Change the current signers and return the old ones

Check if the signers satisfy a certain predicate

Check if a wallet signs a transaction

Check if the transaction has at least a signer

Add a signer to the transaction, at the head of the list of signers, and return the old list of signers

Add signers at the end of the list of signers, and return the old list of signers

Add a signer to the transaction, at the end of the list of signers, and return the old list of signers

Remove signers from the transaction and return the old list of signers

Remove a signer from the transaction and return the old list of signers

Changes the first signer (adds it if there are no signers) and return the old list of signers.

Changes the current validity range, returning the old one

Ensures the skeleton makes for an unconstrained validity range

Sets the left bound of the validity range. Leaves the right bound unchanged

Sets the right bound of the validity range. Leaves the left bound unchanged

Checks if the validity range satisfies a certain predicate

Checks if a given time belongs to the validity range of a transaction

Checks if the current validity range includes the current time

Checks if a given range is included in the validity range of a transaction

Checks if the validity range is empty

Checks if the validity range is unconstrained

Adds a constraint to the current validity range. Returns the old range, and fails is the resulting interval is empty

Centers the validity range around a value with a certain radius

Makes a transaction range equal to a singleton

Makes the transaction validity range comply with the current time

Makes current time comply with the validity range of the transaction under modification. Returns the new current time after the modification; fails if current time is already after the validity range.