Githoney

GitHoney is a smart contract implementation designed to facilitate bounty creation, reward distribution, and other associated transactions on the blockchain. This repository contains the onchain Aiken code and offchain TypeScript code for transaction building and querying.

Environment Variables

Ensure you have a .env file in the githoney/offchain directory with the following variables:

CREATION_FEE = ...
REWARD_FEE = ...
GITHONEY_ADDRESS = ...

Where CREATION_FEE must be a number greater than 2,000,000 (MIN ADA), representing the fee in lovelaces to create a bounty. And REWARD_FEE must be a number between 0 and 10,000, representing the percentage of the reward that will be paid.

Setup

Follow these steps to set up the project for the first time:

1. Navigate to the githoney/offchain directory and install all dependencies:

   npm install

2. Build the code and produce an offchain-1.0.0.tgz file by running:

   npm pack

3. In another npm project, install the library as a local npm package:

   npm i /path/to/offchain-1.0.0.tgz

Running Tests

To run the tests, add additional variables to the .env file:

BLOCKFROST_PROJECT_ID = preprodMySecretBlockFrostProjectId
MAINTAINER_SEED = ...
CONTRIBUTOR_SEED = ...
GITHONEY_SEED = ...

Where the preprodMySecretBlockFrostProjectId can be generated by following this tutorial.

Run all tests together using the following command:

npm run test

Running Individual Tests

To run individual tests, use the following command format:

npm run <test-name>

Replace <test-name> with one of the following options:

• test-create
• test-addrewards
• test-assign
• test-merge
• test-close
• test-claim

Offchain Library API

Bounties Operations

Create BountyUtxo

This transaction creates a BountyUtxo locking the reward assets plus min ADA and a BountyIdToken. It sets the maintainer, deadline, admin, and merged (set to False) in the datum.

/**
 * Builds a `createBounty` transaction. The tx is built in the context of the maintainer wallet.
 * @param settingsUtxo The settings UTxO.
 * @param maintainerAddr The maintainer's address.
 * @param adminAddr The admin's address.
 * @param rewards The reward assets and amount to be locked in the bounty UTxO.
 * @param deadline The deadline for the bounty.
 * @param bounty_id The bounty identifier.
 * @param lucid Lucid instance.
 * @returns The cbor of the unsigned transaction.
 */
async function createBounty(
  settingsUtxo: UTxO,
  maintainerAddr: string,
  adminAddr: string,
  rewards: Assets,
  deadline: bigint,
  bounty_id: string,
  lucid: Lucid
): Promise<string>;

Add Reward

Adds additional reward assets to an existing BountyUtxo.

/**
 * Builds an `addReward` transaction. The tx is built in the context of any wallet.
 * @param settingsUtxo The settings UTxO.
 * @param utxoRef The reference of the last transaction output that contains the bounty UTxO.
 * @param address The address of the current wallet.
 * @param rewards The reward assets and amount to be added.
 * @param lucid Lucid instance.
 * @returns The cbor of the unsigned transaction.
 */
async function addRewards(
  settingsUtxo: UTxO,
  utxoRef: OutRef,
  address: string,
  rewards: Assets,
  lucid: Lucid
): Promise<string>;

Assign Contributor

Sets the contributor's Wallet to the BountyUtxo datum and adds the contributor's min ADA to the value.

/**
 * Builds an `assignContributor` transaction. The tx is built in the context of the contributor wallet.
 * @param settingsUtxo The settings UTxO.
 * @param utxoRef The reference of the last transaction output that contains the bounty UTxO.
 * @param contributorAddr The contributor's address.
 * @param lucid Lucid instance.
 * @returns The cbor of the unsigned transaction.
 */
async function assignContributor(
  settingsUtxo: UTxO,
  utxoRef: OutRef,
  contributorAddr: string,
  lucid: Lucid
): Promise<string>;

Close Bounty

The admin closes the bounty, returning the reward assets to the maintainer and burning the BountyIdToken. If a contributor is assigned, the min ADA is returned to them.

/**
 * Builds a `closeBounty` transaction. The tx is built in the context of the admin wallet.
 * @param settingsUtxo The settings UTxO.
 * @param lucid Lucid instance.
 * @param utxoRef The reference of the last transaction output that contains the bounty UTxO.
 * @returns The cbor of the unsigned transaction.
 */
async function closeBounty(
  settingsUtxo: UTxO,
  utxoRef: OutRef,
  lucid: Lucid
): Promise<string>;

Merge Bounty

Pays GitHoney the reward assets multiplied by the BountyRewardFee. Updates the merged field to True. The contributor's min ADAs remain in the UTxO.

/**
 * Builds a `mergeBounty` transaction. The tx is built in the context of the admin wallet.
 * @param settingsUtxo The settings UTxO.
 * @param utxoRef The reference of the last transaction output that contains the bounty UTxO.
 * @param lucid Lucid instance.
 * @returns The cbor of the unsigned transaction.
 */
async function mergeBounty(
  settingsUtxo: UTxO,
  utxoRef: OutRef,
  lucid: Lucid
): Promise<string>;

Claim Bounty

Pays the contributor the remaining reward assets and burns the BountyIdToken.

/**
 * Builds a `claimBounty` transaction. The tx is built in the context of the contributor wallet.
 * @param settingsUtxo The settings UTxO.
 * @param utxoRef The reference of the last transaction output that contains the bounty UTxO.
 * @param lucid Lucid instance.
 * @param contributorAdrr The contributor's address.
 * @returns The cbor of the unsigned transaction.
 */
async function claimBounty(
  settingsUtxo: UTxO,
  utxoRef: OutRef,
  lucid: Lucid,
  contributorAddr: string
): Promise<string>;

Settings Operations

Deploy Settings

This transaction deploys the GlobalSettings UTxO, which holds the global parameters of the dApp. The NFT policy ID of the minted token identifies the GlobalSettings UTxO. Besides the settings, the utxo will hold also the Githoney Validator code, due to this utxo will be used as reference input of all the redeemers of the Githoney Validator.

/**
 * Builds a `deploy` transaction. The tx is built in the context of the GitHoney address. This transaction configures the global parameters of the dApp, including the creation fee, reward fee, and the GitHoney wallet. These parameters are obtained from the environment configuration.
 * @param lucid Lucid instance.
 * @returns The cbor of the unsigned transaction and a output reference from the asoociated wallet.
 */
async function deploySettings(
  lucid: Lucid
): Promise<{ cbor: string; outRef: OutRef }>;

Update Settings

Updates the global parameters of the dApp, changing the datum of the GlobalSettings UTxO.

/**
 * Builds an `update` transaction. The tx is built in the context of the GitHoney address.
 * @param settingsUtxo The settings UTxO.
 * @param lucid Lucid instance.
 * @param settings The new settings to be updated (Optional).
 * @returns The cbor of the unsigned transaction.
 */
async function updateSettings(
  settingsUtxo: UTxO,
  lucid: Lucid,
  settings?: {
    githoneyWallet: {
      paymentKey: string;
      stakeKey: string | null;
    };
    creationFee: bigint;
    rewardFee: bigint;
  }
): Promise<string>;

Close Settings

Closes the GlobalSettings UTxO, burning the NFT and refunding the ADA locked to githoney.

/**
 * Builds a `closeSettings` transaction. The tx is built in the context of the GitHoney address.
 * @param utxoRef The output reference passed as parameter of the settings nft minting policy,
 * this outRef is returned in the deploySettings operation.
 * @param settingsUtxo The settings UTxO.
 * @param lucid Lucid instance.
 * @returns The cbor of the unsigned transaction.
 */

async function closeSettings(
  utxoRef: OutRef,
  settingsUtxo: UTxO,
  lucid: Lucid
): Promise<string>;