Step by step guide - Trustblock Docs

Using our App
Using our API

Head to app.trustblock.run to sign in. Sign in

Head to your profile

Click on your name in the upper right corner of the screen.

Publish an audit

At the bottom of your profile’s page, you’ll see a “Publish an audit” button redirecting you to the audit publication form once you click on it. Click Publish

Fill the form

Follow the instructions on the form and submit it. Publish

To publish an audit through our API, you must structure your data object in a specific way involving four parts: audit, findings (issues), contracts, and project.

// The full data structure of an audit
type FullAudit = {
    ...auditObject,
    issues: issueObject[],
    contracts: contractObject[],
    project: projectObject
}

1. Audit data

// The audit data structure
type AuditData = {
    // The audit data is at the first level of the full data object.
    name: string, // The name of the audit
    description: string, // The description of the audit
    reportType: 'file' | 'web', // The type of the report
    reportFileCid?: string, // The cid of the IPFS hosted report file
    reportUrl?: string, // The URL of the report
    conductedAt: number, // When the audit was conducted, in milliseconds since the Unix epoch
}

The name and description expected here are not supposed to be the ones of the project audit. Still, the audit itself, e.g., If you audited the liquidity locker of a project named TokenA, the name of the audit would be Liquidity Locker.

File Report
Web Report

To obtain a valid reportFileCid, you will have to perform an upload on our IPFS provider, Pinata. To upload a file, first fetch an upload authorization from our dedicated route. It is restricted to security firms and returns a short-lived signed URL.

Get upload report authorization

Once you have retrieved your authorization response from the previous request, you must upload the file effectively.

Upload file example

const uploadAuthResponse = // Request to the above route

// Get the response's data from the authorization route
const uploadAuth = uploadAuthResponse.data;

// Create a form data to send the file over to Pinata
const formData = new FormData();
formData.append('file', file);
formData.append('network', 'public');

// Perform a POST request on the URL sent by the authorization route
const uploadResponse = await axios.post<{ cid: string }>(uploadAuth.url, formData, {
  maxBodyLength: Infinity,
  headers: {
    'Content-Type': `multipart/form-data;`,
  }
});

// Here you get the reportFileCid needed by the publish audit route.
const reportFileCid = uploadResponse.data.cid;

If you want to publish an audit with a web based report, you will have to submit a valid URL through the reportUrl field.

2. Findings data

Every finding has two attributes: status (IssueStatus) & severity (IssueSeverity).A finding’s status can be fixed, not_fixed or acknowledged. acknowledged means the client read the finding and accepted the risk without fixing it. It is published as not_fixed, with isAcknowledged: true in the public API, and counted separately from open findings.A finding’s severity can either be low, medium, high or critical.

We know security firms use different values for these fields; our goal was to simplify so that everyone can adapt their own system to ours. Open critical findings (not fixed, not acknowledged) are what the cards and the project label report first. We are always welcoming suggestions, so don’t hesitate to contact us!

// The issues data structure
type Issue = {
    name: string, // The name of the issue
    description: string, // The description of the issue
    status: IssueStatus, // The status of the issue
    severity: IssueSeverity // The severity of the issue
}

All your findings must be stored inside the issues list passed to the main request body.

3. Contracts data

Every contract has a type (ContractType) field, which can either be: onChain, offChainPublic or offChainPrivate.Depending on the type, the contract must have different fields.

On-chain
Public Repository
Private Repository

Additionally, to the type field, two other fields are required to submit an on-chain contract: address & chain.chain can either be one of the supported chains.

// The on-chain contract data structure
type OnChainContract = {
    type: 'onChain', // The type of the contract
    chain: supported_chains, // The chain of the contract
    address: 'string' // The address of the contract
}

A public repository contract needs three fields: repositoryUrl, repositoryCommitHash & repositoryFilePath.

type OffChainPublicContract = {
    type: 'offChainPublic', // The type of the contract
    repositoryUrl: 'string', // The repository url of the contract
    repositoryCommitHash: 'string', // The repository commit hash of the contract
    repositoryFilePath: 'string' // The repository file path of the contract
}

A private repository contract needs one field: name.

type OffChainPrivateContract = {
    type: 'offChainPrivate', // The type of the contract
    name: 'string' // The name of the contract
}

4. Project data

Our system will automatically check if the audit’s project already exists in our database by relying on links.website.

type Project = {
  name: string, // The name of the project
  description: string, // The description of the project
  links: {
      website: string, // The website URL of the project
      twitter: string, // The twitter URL of the project (optional)
      discord: string, // The discord URL of the project (optional)
      telegram: string, // The telegram URL of the project (optional)
      github: string, // The github URL of the project (optional)
      youtube: string, // The youtube URL of the project (optional)
      linkedIn: string, // The linkedIn URL of the project (optional)
  },
  tags: ['analytics', 'collectibles', 'finance', 'gaming', 'security', 'social', 'wallet', 'infrastructure', 'privacy', 'identity', 'other'], // Pass as many values as relevant
  chains: supported_chains[], // Pass as many values as relevant
}

chain can either be one of the supported chains.

To make sure your request never fails, pass all the data needed to create a project, including links, name, description, chains and tags.

5. Final data

type FullAudit = {
  name: string, // The name of the audit
  description: string, // The description of the audit
  reportType: 'file' | 'web', // The type of the report
  reportFileCid?: string, // The cid of the IPFS hosted report file
  reportUrl?: string, // The URL of the report
  conductedAt: number, // When the audit was conducted, in milliseconds since the Unix epoch
  issues: [
      {
          name: string, // The name of the issue
          description: string, // The description of the issue
          status: IssueStatus, // The status of the issue
          severity: IssueSeverity // The severity of the issue
      },
      ...
  ],
  contracts: [
      {
          type: 'offChainPublic', // The type of the contract
          repositoryUrl: string, // The URL of the repository, e.g. https://github.com/Uniswap/v3-core
          repositoryCommitHash: string, // The commit hash of the repository, e.g. 4024732be626f4b4299a4314150d5c5471d59ed9
          repositoryFilePath: string, // The path to the audited contract, e.g. contracts/NoDelegateCall.sol
      } | {
          type: 'onChain', // The type of the contract
          chain: supported_chains, // The chain of the contract
          address: 'string' // The address of the contract
      } | {
          type: 'offChainPrivate', // The type of the contract
          name: 'string' // The name of the contract ; usually the contract file name
      },
      ...
  ],
  project: {
      slug: string, // The slug of the project
      domain: string // The domain of the project
      //Only one of the above fields is required.
  } | {
      name: string, // The name of the project
      description: string, // The description of the project
      links: {
          website: string, // The website URL of the project
          twitter: string, // The twitter URL of the project (optional)
          discord: string, // The discord URL of the project (optional)
          telegram: string, // The telegram URL of the project (optional)
          github: string, // The github URL of the project (optional)
          youtube: string, // The youtube URL of the project (optional)
          linkedIn: string, // The linkedIn URL of the project (optional)
      },
      tags: ['analytics', 'collectibles', 'finance', 'gaming', 'security', 'social', 'wallet', 'infrastructure', 'privacy', 'identity', 'other'], // Pass as many values as relevant
      chains: supported_chains[], // Pass as many values as relevant
  }
}

6. Sending the request

Once you have structured your data object, you can send the request to our API.

Publish audit

And then what?

That’s it! Your audit is published and now accessible through our system. Metrics are refreshed by scheduled jobs, so your profile’s metrics update some time after you publish.

Security firm widget

Learn how to show a security firm’s metrics on your website.

The audit you publish is now shown on the project page and returned by the labels, the API and the explorer cards. Check the links below for more information.

Labels Widget

Learn how to add the project label to your website.

Security Data API

Read a project’s published audit state from your own code.

Get upload report authorization

Publish audit

​And then what?

Security firm widget

Labels Widget

Security Data API

And then what?