@blockassetlabs/blaze/README.md

Blockasset Blaze

# Blockasset Labs Blaze

This SDK helps developers get started with the on-chain blaze tool provided by Blockasset Labs. It focuses its API on common use-cases to provide a smooth developer experience.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Addresses](#addresses)
- [Get Started](#get-started)
  - [Create Project](#create-project)
  - [Create Blaze](#create-blaze)
  - [Participate in a Blaze](#participate-in-a-blaze)
- [Installation](#installation)
- [Documentation](#documentation)
  - [Fetch Project Info](#fetch-project-info)
  - [Fetch Blazes of a Project](#fetch-blazes-of-a-project)
  - [Fetch single Blaze info](#fetch-single-blaze-info)
  - [Fetch Entrants data for a single BLaze](#fetch-entrants-data-for-a-single-blaze)
  - [Create Blaze](#create-blaze-1)
  - [Update Blaze](#update-blaze)
  - [Buy Entrants](#buy-tickets)
  - [Resolve Blaze](#resolve-blaze)
  - [Claim Prize](#claim-prize)
  - [Close Blaze](#close-blaze)
  - [Create Project](#create-project-1)
  - [Update Project](#update-project)
  - [Close Project](#close-project)
- [Questions & Support](#questions--support)
- [License](#license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Addresses

Program addresses are the same on devnet, and mainnet-beta.

- Blaze: [`bLz3qYiuoTvBo2PqwwvDiHEcWF1Ghej8uAYV3wbcd82`](https://explorer.solana.com/address/bLz3qYiuoTvBo2PqwwvDiHEcWF1Ghej8uAYV3wbcd82)
- Project: [`prjzeH8Jr5cbwMbzP8BykkRnW88MQ9pcRbqkvL74ewK`](https://explorer.solana.com/address/prjzeH8Jr5cbwMbzP8BykkRnW88MQ9pcRbqkvL74ewK)

## Get Started

### Create Project

To setup a blaze you need to have a `Project` first. If you don't have one, easiest way to create your own project is by using [blockasset labs "Create Project" page](https://labs.blockasset.co/projects/create/).

| Attribute   | Type             | Required | Description                                                                                               |
| ----------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| name        | String           | Yes      | Project name                                                                                              |
| authorities | Array<PublicKey> | Yes      | List of authorities who have access to update project detail and create, update, or close project blazes. |

> If you are interested on creating project using package, check out ["Create Blaze using package" section](#create-blaze-1)

### Create Blaze

You can create `Blaze` for you project by first go to your project page and then create blaze page or simply go to this link:
`https://labs.blockasset.co/projects/<project-id>/create-blaze`

| Attribute             | Type      | Required | Description                                                                       |
| --------------------- | --------- | -------- | --------------------------------------------------------------------------------- |
| Category              | String    | No       | Blaze Category to be saved on chain                                               |
| Prize Mint            | PublicKey | Yes      | Mint address of the NFT that will be sent to the winner once the blaze resolved   |
| Token Mint            | PublicKey | Yes      | Mint address of the token that will be used as payment for purchasing the tickets |
| Entrant Price         | BN        | Yes      | Price of each tickets in lamports                                                 |
| Max Entrants          | Number    | Yes      | Maximum number of entrants in each blaze                                          |
| Start                 | BN        | Yes      | Blaze start timestamp                                                             |
| End                   | BN        | Yes      | Blaze end timestamp                                                               |
| Max Entrants Per User | Number    | Yes      | Maximum percentage of the entries that each wallet can obtain                     |

> If you are interested on creating blaze using package, check out ["Create Project using package" section](#create-project-1)

### Participate in a Blaze

Your users can participate in your blaze by going to this address: `https://labs.blockasset.co/projects/<blazee-id>`

| Attribute | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| quantity  | Number | Yes      | Number of entries that user wants to obtain |

## Installation

Installing the package using [yarn](https://yarnpkg.com/lang/en/):

```sh
yarn add @blockassetlabs/project @blockassetlabs/blaze
```

You can also use [npm](https://www.npmjs.com/) instead, if you'd like:

```sh
npm install @blockassetlabs/project @blockassetlabs/blaze
```

🔥 **Pro Tip**: Check out our implementations on ["BlockassetLabs UI" repository](https://github.com/Blockasset/blockasset-labs-ui).

## Documentation

### Fetch Project Info

```ts
import { getProject } from '@blockassetlabs/project';

const project = getProject(connection, projectId);
```

### Fetch Blazes of a Project

```ts
import { getBlazesByProjectId } from '@blockassetlabs/blaze';

const blazes = await getBlazesByProjectId(connection, projectId);
```

### Fetch single Blaze info

```ts
import { getBlaze } from '@blockassetlabs/blaze';

const blazes = await getBlaze(connection, blazeId);
```

### Fetch Entrants data for a single BLaze

```ts
import { getEntrants } from '@blockassetlabs/blaze';

const blazes = await getEntrants(connection, entrantId);
```

### Create Blaze

> This transaction can only be called by one of the project authorities

```ts
import { createBlaze } from '@blockassetlabs/blaze';

const { signature, blazeId } = await createBlaze(connection, wallet as Wallet, {
  // Project Id
  projectId: project.pubkey,

  // Mint address of blaze prize NFT
  prizeMint: new PublicKey(formValues.prizeMint),

  // Mint address of the acceptable token for entrance fee
  // If not provided the payment will be based on sol
  tokenMint: formValues.tokenMint ?? new PublicKey(formValues.tokenMint),

  // Wallet address of treasury account for the entrance fees
  // No need to set any if the burn rate is 100
  treasury: formValues.tokenMint ?? new PublicKey(formValues.treasury),

  // Burn rate of the tokenMint
  // Can be between 1 to 100
  burnRate: formValues.burnRate ?? new PublicKey(formValues.burnRate),

  // Entrance fee for acquiring 1 blaze entrance in natural amounts
  entrantFee: new BN(formValues.entrantFee),

  // Total entrants of a blaze
  maxEntrants: formValues.maxEntrants,

  // Maximum percentage of the total entrants that each wallet can redeem
  // Default is 100
  maxEntrantsPerWalletRate: formValues.maxEntrantsPerWalletRate,

  // Start date timestamp
  start: new BN(formValues.start.getTime() / 1000),

  // End date timestamp
  end: new BN(formValues.end.getTime() / 1000),

  // Additional info
  category: formValues.category
});
```

### Update Blaze

> This transaction can only be called by one of the project authorities

```ts
import { updateBlaze } from '@blockassetlabs/blaze';

const signature = await updateBlaze(connection, wallet as Wallet, {
  // Blaze Id
  blazeId: activeBlaze.pubkey,

  // Project Id
  projectId: project.pubkey,

  // Mint address of blaze prize NFT
  prizeMint: new PublicKey(formValues.prizeMint),

  // Mint address of the acceptable token for entrance fee
  // If not provided the payment will be based on sol
  tokenMint: formValues.tokenMint ?? new PublicKey(formValues.tokenMint),

  // Wallet address of treasury account for the entrance fees
  // No need to set any if the burn rate is 100
  treasury: formValues.tokenMint ?? new PublicKey(formValues.treasury),

  // Burn rate of the tokenMint
  // Can be between 1 to 100
  burnRate: formValues.burnRate ?? new PublicKey(formValues.burnRate),

  // Entrance fee for acquiring 1 blaze entrance in natural amounts
  entrantFee: new BN(formValues.entrantFee),

  // Total entrants of a blaze
  maxEntrants: formValues.maxEntrants,

  // Maximum percentage of the total entrants that each wallet can redeem
  // Default is 100
  maxEntrantsPerWalletRate: formValues.maxEntrantsPerWalletRate,

  // Start date timestamp
  start: new BN(formValues.start.getTime() / 1000),

  // End date timestamp
  end: new BN(formValues.end.getTime() / 1000),

  // Additional info
  category: formValues.category
});
```

### Buy Entrants

> This is a public transaction and can only be called by anyone

```ts
import { redeemEntrants } from '@blockassetlabs/blaze';

const signature = await redeemEntrants(connection, wallet as Wallet, {
  // Number of entrants
  quantity,

  // Blaze id
  blazeId: activeBlaze.pubkey
});
```

### Resolve Blaze

Resolving the blaze is an on-chain weighted random selection

> This is a public transaction, so anybody can resolve the blaze

```ts
import { resolveBlaze } from '@blockassetlabs/blaze';

const signature = await resolveBlaze(
  new Transaction(),
  connection,
  wallet as Wallet,
  {
    // Blaze id
    blazeId: activeBlaze.pubkey
  }
);
```

### Claim Prize

> Only the blaze winner can call call this transaction to claim its prize

```ts
import { claimPrize } from '@blockassetlabs/blaze';

const signature = await claimPrize(connection, wallet as Wallet, {
  // Blaze id
  blazeId: activeBlaze.pubkey
});
```

### Close Blaze

It's possible to recover the funds used to pay rent for the data stored on-chain by closing the Blaze.

- If the prize is not claimed yet this action will transfer back the prize to the caller account.
- This action is not recoverable and permanently remove the access to the blaze.

> This transaction can only be called by one of the project authorities

```ts
import { closeBlaze } from '@blockassetlabs/blaze';

const signature = await closeBlaze(connection, wallet as Wallet, {
  // Blaze id
  blazeId: activeBlaze.pubkey
});
```

### Create Project

> This is a public transaction, so anybody can create a new project

```ts
import { withInitProject } from '@blockassetlabs/project';

const [transaction, projectId] = await withInitProject(
  new Transaction(),
  connection,
  wallet as Wallet,
  {
    authorities: [wallet.publicKey],
    name: formValues.name
  }
);
await executeTransaction(connection, wallet as Wallet, transaction);
```

### Update Project

> This transaction can only be called by one of the project authorities

```ts
import { withUpdateProject } from '@blockassetlabs/project';

const transaction = await withUpdateProject(
  new Transaction(),
  connection,
  wallet as Wallet,
  {
    projectId: projectId,
    authorities: [wallet.publicKey],
    name: formValues.name
  }
);
await executeTransaction(connection, wallet as Wallet, transaction);
```

### Close Project

It's possible to recover the funds used to pay rent for the data stored on-chain by closing the Project.

- Although closing a project will not affect any of its blazes, it's highly recommended to close its blazes first because once the project closed, you will no longer have access to its blazes to modify or close.
- This action is not recoverable and permanently remove the access to the project.

> This transaction can only be called by one of the project authorities

```ts
import { withUpdateProject } from '@blockassetlabs/project';

const transaction = await withCloseProject(
  new Transaction(),
  connection,
  wallet as Wallet,
  {
    projectId: projectId
  }
);
await executeTransaction(connection, wallet as Wallet, transaction);
```

## Questions & Support

If you are developing using Blockasset contracts and libraries, feel free to reach out for support on Discord. We will work with you or your team to answer questions, provide development support and discuss new feature requests.

For issues please, file a GitHub issue.

> https://discord.gg/blockasset

## License