How to Integrate us

Here you'll find the basic flow in order to use Trustless Work API. In this flows tutorial, we'll use as an example the integration of Trustless Work in our dApp.

Important Notes

Be sure to checkout the Smart Escrow Design section for visual helpers.

• We are using the Stellar Wallet Kit library.

Welcome! | Stellar Wallets Kit

• We are using axios library with a pre-configuration with the Trustless Work URL and the Bearer token.

import axios from "axios";

const http = axios.create({
  baseURL: process.env.API_URL || "", // Trustless Work API URL
  timeout: 60000, // time
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.API_KEY}`, // Trustless Work API Key
  },
});

export default http;

• You should connect to your favorite wallet, if you are in development, Freighter is recommended.

Stellar Wallets

• You'll be able to see the Escrow entity in the page below.

Schema

---

Steps

1. Initialize Escrow

The escrow contract must be deployed, which in turn initializes the escrow with its metadata.

Payload Type:

export type EscrowPayload = Omit<
  Escrow,
  "user" | "createdAt" | "updatedAt" | "id"
>;

Execute Endpoint:

interface EscrowPayloadWithSigner extends EscrowPayload {
  signer?: string;
}

export const initializeEscrow = async (
  payload: EscrowPayloadWithSigner,
) => {
  try {
  
    // Get the address
    const { address } = await kit.getAddress();
  
    // Add the signer
    const payloadWithSigner: EscrowPayloadWithSigner = {
      ...payload,
      signer: address,
    };

    // Execute the endpoint
    const response = await http.post(
      "/deployer/invoke-deployer-contract",
      payloadWithSigner,
    );

    // Get the unsigned transaction hash
    const { unsignedTransaction } = response.data;

    // Sign the transaction by wallet
    const { signedTxXdr } = await signTransaction(unsignedTransaction, {
      address,
      networkPassphrase: WalletNetwork.TESTNET,
    });

    // Send the transaction to Stellar Network
    const tx = await http.post("/helper/send-transaction", {
      signedXdr: signedTxXdr,
      returnValueIsRequired: true,
    });

    const { data } = tx;

    return data;
  } catch (error: unknown) {
    // catch code ...
  }
};

References:

Initialize Escrow

Initiation Phase

1. Fund Escrow

Each escrow must be funded before the release funds or resolve dispute. It's important to clarify that you can fund the escrow in any moment, but just for this case, we'll fund it in the beginning.

Payload Type:

export type FundEscrowPayload = Pick<Escrow, "amount" | "contractId"> & {
  signer: string;
};

Execute Endpoint:

export const fundEscrow = async (payload: FundEscrowPayload) => {
  try {
  
    // Get the address
    const { address } = await kit.getAddress();
  
    // Execute the endpoint
    const response = await http.post("/escrow/fund-escrow", payload);

    // Get the unsigned transaction hash
    const { unsignedTransaction } = response.data;

    // Sign the transaction by wallet
    const { signedTxXdr } = await signTransaction(unsignedTransaction, {
      address,
      networkPassphrase: WalletNetwork.TESTNET,
    });

    // Send the transaction to Stellar Network
    const tx = await http.post("/helper/send-transaction", {
      signedXdr: signedTxXdr,
    });

    const { data } = tx;
    return data;
  } catch (error: unknown) {
    // catch code...
  }
};

References:

Fund Escrow

Funding Phase

---

These endpoints don't have any specific order to execute them

1. Edit Milestones

You can edit the milestones in any moment, but just the Platform Entity will be able to do it. Only the pending milestones will be editable.

Payload Type:

export type EditMilestonesPayload = {
  contractId: string;
  escrow: EscrowPayload;
  signer: string;
};

Execute Endpoint:

export const editMilestones = async (payload: EditMilestonesPayload) => {
  try {
  
    // Get the address
    const { address } = await kit.getAddress();
  
    // Execute the endpoint
    const response = await http.put(
      "/escrow/update-escrow-by-contract-id",
      payload,
    );

    // Get the unsigned transaction hash
    const { unsignedTransaction } = response.data;

    // Sign the transaction by wallet
    const { signedTxXdr } = await signTransaction(unsignedTransaction, {
      address,
      networkPassphrase: WalletNetwork.TESTNET,
    });

    // Send the transaction to Stellar Network
    const tx = await http.post("/helper/send-transaction", {
      signedXdr: signedTxXdr,
    });

    const { data } = tx;
    return data;
  } catch (error: unknown) {
    // catch code...
  }
};

References:

ADD REFERENCES

1. Change Milestone Status

With this endpoint you'll change the status of the milestones, but just the Service Provider will be able to do it.

Payload Type:

export type ChangeMilestoneStatusPayload = {
  contractId?: string;
  milestoneIndex: string;
  newStatus: MilestoneStatus; // you can custom your status
  serviceProvider?: string;
};

Execute Endpoint:

export const changeMilestoneStatus = async (
  payload: ChangeMilestoneStatusPayload,
) => {
  try {
  
    // Get the address
    const { address } = await kit.getAddress();
  
    // Execute the endpoint
    const response = await http.post(
      "/escrow/change-milestone-status",
      payload,
    );

    // Get the unsigned transaction hash
    const { unsignedTransaction } = response.data;

    // Sign the transaction by wallet
    const { signedTxXdr } = await signTransaction(unsignedTransaction, {
      address,
      networkPassphrase: WalletNetwork.TESTNET,
    });

    // Send the transaction to Stellar Network
    const tx = await http.post("/helper/send-transaction", {
      signedXdr: signedTxXdr,
    });

    const { data } = tx;
    return data;
  } catch (error: unknown) {
   // catch code...
  }
};

References:

Complete phase

Change Milestone Status

1. Change Milestone Flag

With this endpoint you'll approve the milestones, but just the Approver will be able to do it.

Payload Type:

export type ChangeMilestoneFlagPayload = Omit<
  ChangeMilestoneStatusPayload,
  "serviceProvider" | "newStatus"
> & {
  approver?: string;
  newFlag: boolean;
};

Execute Endpoint:

export const changeMilestoneFlag = async (
  payload: ChangeMilestoneFlagPayload,
) => {
  try {
  
    // Get the address
    const { address } = await kit.getAddress();
  
    // Execute the endpoint
    const response = await http.post(
      "/escrow/change-milestone-flag",
      payload,
    );

    // Get the unsigned transaction hash
    const { unsignedTransaction } = response.data;

    // Sign the transaction by wallet
    const { signedTxXdr } = await signTransaction(unsignedTransaction, {
      address,
      networkPassphrase: WalletNetwork.TESTNET,
    });

    // Send the transaction to Stellar Network
    const tx = await http.post("/helper/send-transaction", {
      signedXdr: signedTxXdr,
    });

    const { data } = tx;
    return data;
  } catch (error: unknown) {
   // catch code...
  }
};

References:

Approval phase

Change Milestone Flag

1. Change Dispute Flag

In any moment, the approver or service provider can start a dispute. This cannot executed without funds in the escrow's balance.

Payload Type:

export type StartDisputePayload = Pick<Escrow, "contractId"> & {
  signer: string;
};

Execute Endpoint:

export const startDispute = async (
  payload: StartDisputePayload,
) => {
  try {
  
    // Get the address
    const { address } = await kit.getAddress();
  
    // Execute the endpoint
    const response = await http.post(
      "/escrow/change-dispute-flag",
      payload,
    );

    // Get the unsigned transaction hash
    const { unsignedTransaction } = response.data;

    // Sign the transaction by wallet
    const { signedTxXdr } = await signTransaction(unsignedTransaction, {
      address,
      networkPassphrase: WalletNetwork.TESTNET,
    });

    // Send the transaction to Stellar Network
    const tx = await http.post("/helper/send-transaction", {
      signedXdr: signedTxXdr,
    });

    const { data } = tx;
    return data;
  } catch (error: unknown) {
   // catch code...
  }
};

References:

Change Dispute Flag

---

Case #1: If all the milestones were completed and approved, you'll be able to release the funds.

1. Distribute Escrow Earnings

When the escrow is ready to be released, you can do it with this endpoint. Only the release signer can do it.

Payload Type:

export type DistributeEscrowEarningsEscrowPayload = Pick<Escrow, "contractId"> &
  Partial<Pick<Escrow, "serviceProvider" | "releaseSigner">> & {
    signer: string;
  };

Execute Endpoint:

export const distributeEscrowEarnings = async (
  payload: DistributeEscrowEarningsEscrowPayload,
) => {
  try {
  
    // Get the address
    const { address } = await kit.getAddress();
  
    // Execute the endpoint
    const response = await http.post(
      "/escrow/distribute-escrow-earnings",
      payload,
    );

    // Get the unsigned transaction hash
    const { unsignedTransaction } = response.data;

    // Sign the transaction by wallet
    const { signedTxXdr } = await signTransaction(unsignedTransaction, {
      address,
      networkPassphrase: WalletNetwork.TESTNET,
    });

    // Send the transaction to Stellar Network
    const tx = await http.post("/helper/send-transaction", {
      signedXdr: signedTxXdr,
    });

    const { data } = tx;
    return data;
  } catch (error: unknown) {
   // catch code...
  }
};

References:

Release phase

Distribute Escrow Earnings

Case #2: If the approver or service provider started the dispute, you'll be able to resolve the dispute.

1. Resolve Dispute

When the escrow is in dispute, you can resolve it with this endpoint. Only the dispute resolver can do it.

Payload Type:

export type ResolveDisputePayload = Pick<Escrow, "contractId"> &
  Partial<Pick<Escrow, "disputeResolver">> & {
    approverFunds: string;
    serviceProviderFunds: string;
  };

Execute Endpoint:

export const resolveDispute = async (
  payload: ResolveDisputePayload,
) => {
  try {
  
    // Get the address
    const { address } = await kit.getAddress();
  
    // Execute the endpoint
    const response = await http.post(
      "/escrow/resolving-disputes",
      payload,
    );

    // Get the unsigned transaction hash
    const { unsignedTransaction } = response.data;

    // Sign the transaction by wallet
    const { signedTxXdr } = await signTransaction(unsignedTransaction, {
      address,
      networkPassphrase: WalletNetwork.TESTNET,
    });

    // Send the transaction to Stellar Network
    const tx = await http.post("/helper/send-transaction", {
      signedXdr: signedTxXdr,
    });

    const { data } = tx;
    return data;
  } catch (error: unknown) {
   // catch code...
  }
};

References:

Dispute Resolution

Resolve Dispute

IMPORTANT NOTE

All endpoints related to escrow management return the transaction unsigned. This is done by means of a string returned in XDR (External Data Representation) format, which is a format that stellar uses to encode transactions. This string is what you should use to sign the transaction with the wallet of your choice. After being signed it will return the transaction signed in the same way by means of a string in XDR format.

• This string is the one that must be sent to the next endpoint for the transaction to be sent to the Stellar network:

https://dev.api.trustlesswork.com/helper/send-transactiondev.api.trustlesswork.com

That's all, thanks.