Listings Workflow Diagrams

Buying, Offering and Cancellation workflow details

Accept a sale or offer

This scheme illustrate the process to buy nfts and to accept an offer.

   ┌─────┐          ┌─────────┐            ┌──────────────────────────┐
   │Front│          │ Backend │            │ Exchange Smart Contract  │
   └──┬──┘          └─────┬───┘            └──────────────┬───────────┘
      │                   │                               │
      │1.authorizeBasket()│                               │
      │──────────────────>│                               │
      │                   │                               │
      │     2.Tickets     │                               │
      │<──────────────────│                               │
      │                   │                               │
      │3.BulkBuy(Tickets) or 3.1.bulkOffersAccept(Tickets)│
      │──────────────────────────────────────────────────>│
   ┌──┴──┐            ┌───┴───┐               ┌───────────┴───────────┐
   │Front│            │Backend│               │Exchange Smart Contract│
   └─────┘            └───────┘               └───────────────────────┘

1. API authorizeBasket()

You will have to use authorizeBasket mutation with the following parameters :

• kind wich describe the listing type (sale or offer)

• buyer_address or seller_address depending on the listing type

• And the basketItems referencing the listing id and the bought quantity

Graphql Example for direct sale

mutation AuthorizeSaleBasket(
  $kind: DealKind!
  $userAddress: Address!
  $basketItems: [BasketItem!]!
) {
  authorizeBasket(
    input: { kind: $kind, basket: $basketItems, buyer_address: $userAddress }
  ) {
    kind
    sales_tickets {
      seller
      token_address
      token_id
      in_sale_amount
      unitary_price
      expiration_ts
      starting_ts
      nonce
      chain_id
      min_unitary_price
      managed
      seller_signature
      buyer
      nft_recipient
      amount_bought
      sale_id
      kalao_fees
      community_fees
      extern_fees
      extern_recipient
      validator_signature_expiration_ts
      activate_royalties
      validator_signature
    }
  }
}

Example Parameters

{
  "kind": "sale",
  "userAddress": "0xaaEFD0E3aA0aA1874AFE582C418eDA0bb5F70373",
  "basketItems": [
    {
      "id": "af8be493-e78c-441c-a389-825d9f4a87f0",
      "amount": "1"
    }
  ]
}

2. Tickets

If your order is valid, you will receive one or many sales_tickets to use on smart contract interaction described on the next step.

3. Smart Contract bulkBuy()

This method refers to the Smart Contract bulkBuy method. See sample call below with ether.js

import { ethers } from "ethers";
let contract = new ethers.Contract(
  kalao_exchange_contract_address,
  abi,
  provider
);
let contractWithSigner = contract.connect(signer);

try {
  let tx = await contractWithSigner.bulkBuy(sales_tickets, {
    value: sales_tickets[0].unitary_price,
  });
  console.log("bulkOffersAccept tx hash: ", tx.hash);
  await tx.wait();
  console.log("bulkOffersAccept Transaction confirmed sale is concluded");
} catch (e) {
  let prse = e.error?.message.split(",") || e;
  let contractError = prse[0]?.split("reason=")[1] || e;
  console.error("Something bad happened : ", contractError);
}

3.1 Smart Contract bulkOffersAccept()

This method refer to Smart Contract bulkOffersAccept method.

Cancel a sale or offer

When a sale or an offer has been made, it can be cancelled by a simple backend call when no buying tickets are used, otherwise a call to smart contract is required to ensure that no one can override this cancellation.

Note : Requesting user needs to be authentified via a call to cancelNonce() and a signature on the returned payload as explained in Cancel sales and offers.

     ┌─────┐                                      ┌───────┐┌───────────────────────┐
     │Front│                                      │Backend││Exchange Smart Contract│
     └──┬──┘                                      └───┬───┘└───────────┬───────────┘
        │                                             │                │
        │            1.cancelDeal()                   │                │
        │────────────────────────────────────────────>│                │
        │                                             │                │
        │cancelled? yes = OK, no = Tickets            │                │
        │<────────────────────────────────────────────│                │
        │                                             │                │
        │  no => 2.bulkCancel(Tickets) or 2.1.bulkOfferCancel(Tickets) │
        │─────────────────────────────────────────────────────────────>│
     ┌──┴──┐                                      ┌───┴───┐┌───────────┴───────────┐
     │Front│                                      │Backend││Exchange Smart Contract│
     └─────┘                                      └───────┘└───────────────────────┘

1. API cancelDeal()

With you hex encoded signature and the nonce, you may finalise the listing cancellation by calling the cancelDeal mutation with the below parameters :

• The previously obtained $nonce as a string,

• Your hex signature on the $signature param,

• Your user hex address on the user_address param,

• And the original request.

mutation CancelSale(
  $userAddress: Address!
  $dealID: String!
  $nonce: String!
  $signature: String!
) {
  cancelDeal(
    user_address: $userAddress
    cancel_nonce: $nonce
    cancel_signature: $signature
    input: { kind: sale, uuid: $dealID }
  ) {
    infos
    complete
    sale_ticket {
      managed
      seller
      sale_id
      starting_ts
      seller_signature
      expiration_ts
      in_sale_amount
      validator_signature
    }
  }
}

Params :

{
  "userAddress": "0x12776a9dab38cc9a164815053737f8b050ffe42f",
  "dealID": "c10e20e5-cd13-4e03-b14a-ef97eb2adaf8",
  "nonce": "\nYou are requesting to cancel deal id c10e20e5-cd13-4e03-b14a-ef97eb2adaf8 as \naddress 0x12776a9dab38cc9a164815053737f8b050ffe42f owner.\n\nVersion: 1\nChain ID: 43113\nNonce: hzRGmvPZtd\nIssued At: 2022-10-25T10:52:24Z\nExpire At: 2022-10-25T11:02:24Z\n",
  "signature": "0x12776a9dab38cc9a164815053737f8b050ffe42f53737f8b050ffe42f"
}

2. SmartContract bulkCancel()

This method refers to the Smart Contract bulkCancel method.

2.1 SmartContract bulkOfferCancel()

This method refers to the Smart Contract bulkOfferCancel method.