Event

Instantiation

• Have your seed phrase prepared with a few ADA inside
• Have your provider prepared

Set up your Event Builder

Mainnet

const winterEvent = new EventFactory('Mainnet');

Preview

const winterEvent = new EventFactory('Preview');

Preprod

const winterEvent = new EventFactory('Preprod');

Custom

const winterEvent = new EventFactory('Custom');

Set up your provider

Blockfrost

const provider = new Blockfrost('<apiUrl>', '<projectId>');
await winterEvent.setProvider(provider, {
    seed: '<seedPhrase>'
});

Kupmios

const provider = new Kupmios('http://localhost:1442', 'ws://localhost:1337');
await winterEvent.setProvider(provider, {
    seed: '<seedPhrase>'
});

Maestro

const provider = new Maestro({
    network: '<network>',
    apiKey: '<Your-API-Key>',
    turboSubmit: false
});
await winterEvent.setProvider(provider, {
    seed: '<seedPhrase>'
});

Custom

class MyProvider { ... }
const provider = new MyProvider();
await winterEvent.setProvider(provider, {
    seed: '<seedPhrase>'
});

Additional Settings

Along with seed, there are extra optional options to specify address type, account index, and seed password

await winterEvent.setProvider(provider, {
    seed: '<seedPhrase>',
    options: {
        addressType: 'Base',
        accountIndex: 1,
        password: '<myPassword>'
    }
});

You may also use a private key instead of seed phrase

await winterEvent.setProvider(provider, undefined, '<privKey>');

Set up your contract

Here you must set your immutable data for your commodity

const walletAddress = await winterEvent.getWalletAddress();
const walletAddressPK = winterEvent.getAddressPK(walletAddress);

await winterEvent.setObjectContract({
    protocolVersion: 1n,
    dataReference: fromText('harvest'),
    eventCreationInfo: fromText(''),
    signers: [walletAddressPK]
});

protocolVersion

This denotes which version of the respective protocol is being used. This should be a bigint.

dataReference

This can be any arbitrary data. Perhaps an IPFS link. Data must be in the form of a hex string.

eventCreationInfo

This must be the original txId during the creation of the contract. Since there is no way to determine it before transaction is built, it should be an empty string.

signers

This represents all authorized signers who can interact with the contract. It is an array of strings. The strings must be the address payment credential hash of the respective signer.

Minting

A token known as a singleton must be minted to the contract to easily identify the proper utxo. It is known as a singleton since only one of them will be in existence just as an NFT!

Continue only if the entire instantiation step is complete. It is important that your smart contract parameters are correctly set!

const name = 'testSingletonTracker';
const walletUtxos = await winterEvent.getWalletUtxos();

const completeTx = await winterEvent.mintSingleton(name, walletUtxos);
const signedTx = await completeTx.sign().complete();
const txHash = await signedTx.submit();
await winterEvent.waitForTx(txHash); // optional, this waits for transaction confirmation

Recreation

This allows data and singleton to be transferred to a new utxo. A fee of 1 ADA is paid to winter protocol. It is paid once per transaction no matter the input count.

Utxo Selection

It is up to the user to have their inputs selected, however, this library does contain some helper methods.

An exact utxo can be selected as such

const utxos = await winterEvent.getUtxosByOutRef([
    {
        txHash: '<txHash>',
        outputIndex: <index>
    }
]);

A series of utxos from the same contract address can be selected, all with different singletons and datums. The only requirement is that they all share intersecting signers.

The library will automatically ensure proper datum recreation, lovelace transfer, and singleton transfer.

Since recreation is only done to correct the data reference, a new value must be passed into the function. As recreate takes in an array of utxos, the newDataRef must also be an array of hex strings; each of which that correspond to the utxo at the same index.

In the example below, there is only one utxo, therefore there will be only one element in the newDataRef array.

Transaction Building

const newDataRef = ["deadbeef"]
const completeTx = await winterEvent.recreate(walletAddress, utxos, newDataRef);
const signedTx = await completeTx.sign().complete();
const txHash = await signedTx.submit();
await winterEvent.waitForTx(txHash);

Spending

This spends the utxo and burns the singleton that tracks it. A fee of 1 ADA is paid to winter protocol. It is paid once per transaction no matter the input count.

Utxo Selection

It is up to the user to have their inputs selected, however, this library does contain some helper methods.

An exact utxo can be selected as such

const utxos = await winterEvent.getUtxosByOutRef([
    {
        txHash: '<txHash>',
        outputIndex: <index>
    }
]);

A series of utxos from the same contract address can be selected, all with different singletons and datums. The only requirement is that they all share intersecting signers.

The library will automatically ensure proper lovelace transfer and singleton burn.

Transaction Building

If a new instance is created and the singleton contract is not readily available, koios can be used to extract the script.

Note that Local only works if the same event instance has minted the singleton. winterEvent.singletonContract is only set when mint function is called.

Local

const completeTx = await winterEvent.spend(walletAddress, walletAddress, utxos, undefined, [
    winterEvent.singletonContract
]);
const signedTx = await completeTx.sign().complete();
const txHash = await signedTx.submit();
await winterEvent.waitForTx(txHash);

Koios

const completeTx = await winterEvent.spend(walletAddress, walletAddress, utxos, '<koiosUrl>');
const signedTx = await completeTx.sign().complete();
const txHash = await signedTx.submit();
await winterEvent.waitForTx(txHash);