Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding embedding docs #268

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/bot-development-patterns.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,11 @@

Labels provide a way to add more contextual data to findings generated by Forta bots. This information can be used to answer questions like "which addresses have been involved in flashloan attacks?" or "which blocks contain exploits?".

* [Using embeddings](https://docs.forta.network/en/latest/embeddings/)

Embeddings provide a way to store vector representations of entities, and query by the similarities of entities.
information can be used to answer questions like "which addresses are the most similar addresses to this scammer?" or

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Information [capital i after point]

"Are there any addresses extremely similar to this attacker?".


* [Error monitoring](https://docs.forta.network/en/latest/error-monitoring/)
Expand Down
110 changes: 110 additions & 0 deletions docs/embeddings.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# Embeddings

Embeddings provide a way to store vector representations of entities, and query by the similarities of entities.
information can be used to answer questions like "which addresses are the most similar addresses to this scammer?" or

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Information [capital i after point]

"Are there any addresses extremely similar to this attacker?". The Forta bot SDK provides an easy way to specify
embedding which this page will describe.

## Adding embeddings

Easiest way to share an embedding is to do it within a label. Bots can return labels as part of their findings,
which now includes embeddings. Here is an example of adding embeddings:

```javascript
Finding.from({
name: "High Tether Transfer",
description: "High amount of USDT transferred",
alertId: "FORTA-1",
severity: FindingSeverity.High,
type: FindingType.Suspicious,
labels: [
{
entityType: EntityType.Address,
entity: "0x062dB680e5DCA653248432fC1B4F788E41c83234",
label: "attacker",
confidence: 0.9,
embedding: [0.1121, 0.522533, 0.952825]
}
],
});
```

You can only add one embedding per label

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

point at the end


## Removing embeddings

To remove embeddings, you simply need to remove the label attached to the embedding. If you send the same label and
set the `remove` boolean field to true, It will remove the label and associated embedding

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

point at the end


```javascript
Finding.from({
name: "High Tether Transfer",
description: "High amount of USDT transferred",
alertId: "FORTA-1",
severity: FindingSeverity.High,
type: FindingType.Suspicious,
labels: [
{
entityType: EntityType.Transaction,
entity:
"0xfb141d179b40d895ba227c26860d7f49744fe50bdf89a6e6e21978c09c7ac05f",
label: "flashloan-attack",
confidence: 0.7,
remove: true,
},
],
});
```

Notice that all values of the label are the same, but we just added `remove: true`.

## Querying embeddings

You can think about embeddings as a new feature on top of labels. To make a similarity search based on embeddings, you need to use the boolean flag `state: true`. The reason for that
is the state will render all previous FP-mitigations and do a similarity search on the latest version of your label.

```graphql
query Labels($input: LabelsInput) {
labels(input: $input) {
labels {
id
label {
confidence
embedding
entity
entityType
label
metadata
remove
uniqueKey
}
}
}
}
```

This input will give you the most similar labels to your vector:
```graphql
{
"input": {
"first":10,
"state": true,
"embedding": [0.1,0.2,0.1],
}
}
```

If you want to only get embeddings lower than a specific distance, you can add a distance filter to your query:
```graphql
{
"input": {
"first":10,
"state": true,
"embedding": [0.1,0.2,0.1],
"distance": 0.4
}
}
```


You can query for embeddings using the [Forta GraphQL API](https://docs.forta.network/en/latest/forta-api-reference/).
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ nav:
- Index: bot-development-patterns.md
- Best Practices: best-practices.md
- Adding labels to findings: labels.md
- Using embeddings: embeddings.md
- Error monitoring: error-monitoring.md
- Increasing bot throughput: sharding.md
- Long running tasks: long-running-tasks.md
Expand Down