Private Sets

Private Sets enable users to put together arbitrary groupings of Ethereum validators, and to easily track aggregated statistics of these persistent clusters.

Introducing Private Sets

Private sets empower organizations to implement sophisticated monitoring strategies, including A/B testing, performance benchmarking, and multivariate analysis.

By organizing validators into Private sets, organizations can execute controlled experiments and analyses to assess various aspects of their validators' performance. This strategic grouping not only enhances the understanding of individual and collective validator efficiency but also informs decisions aimed at optimizing overall performance.

In the sections below you will find everything you need to unlock the full power of working with Private Sets on the Rated API.

Get all tags

This endpoint returns all the tags that are associated with your organization.

GET/tags

Query parameters

Response

200400

Successful Response

Body

application/json

previousPrevious

nextNext

pages*Pages

results*Results

Request

JavaScriptCurlPython

const response = await fetch('/tags', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "previous": "https://endpoint?limit=10&offset=10",
  "next": "https://endpoint?limit=10&offset=10",
  "pages": 10,
  "results": [
    {
      "id": "96cbc789-5a03-4110-abeb-67f5d4f65323",
      "name": "us-west-1",
      "network": "holesky",
      "organizationId": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
      "createdBy": "467c1246-be63-40c2-82c3-10f80d3238bb",
      "createdAt": "2024-03-31T18:13:27.584133"
    }
  ]
}

---

Create a new tag

To call a private set's effectiveness, you must first create a tag which acts as a unique identifier for the set. This endpoint allows you to create a new tag. You must give your tag a name. The response will contain the tag id which you will then use to add validators using the add validator endpoint.

POST/tags

Header parameters

Body

application/json

name*Name

Response

201400

Successful Response

Body

application/json

id*Id

name*Name

network*Network

An enumeration.

mainnetpraterholesky

organizationId*Organizationid

createdBy*Createdby

createdAt*Createdat

updatedAtUpdatedat

Request

JavaScriptCurlPython

const response = await fetch('/tags', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "us-west-1"
    }),
});
const data = await response.json();

Response

201400

{
  "id": "96cbc789-5a03-4110-abeb-67f5d4f65323",
  "name": "us-west-1",
  "network": "holesky",
  "organizationId": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
  "createdBy": "467c1246-be63-40c2-82c3-10f80d3238bb",
  "createdAt": "2024-03-31T18:13:27.584133"
}

---

Get details about a tag

This endpoint will return the details on a tag including its name, id and when it was created.

GET/tags/{id}

Path parameters

id*Id

Header parameters

Response

200400

Successful Response

Body

application/json

id*Id

name*Name

network*Network

An enumeration.

mainnetpraterholesky

organizationId*Organizationid

createdBy*Createdby

createdAt*Createdat

updatedAtUpdatedat

Request

JavaScriptCurlPython

const response = await fetch('/tags/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "id": "96cbc789-5a03-4110-abeb-67f5d4f65323",
  "name": "us-west-1",
  "network": "holesky",
  "organizationId": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
  "createdBy": "467c1246-be63-40c2-82c3-10f80d3238bb",
  "createdAt": "2024-03-31T18:13:27.584133"
}

---

Update a tag

This endpoint allows you to update the name associated with your tag.

PATCH/tags/{id}

Path parameters

id*Id

Header parameters

Body

application/json

name*Name

Response

200400422

Successful Response

Body

application/json

id*Id

name*Name

network*Network

An enumeration.

mainnetpraterholesky

organizationId*Organizationid

createdBy*Createdby

createdAt*Createdat

updatedAtUpdatedat

Request

JavaScriptCurlPython

const response = await fetch('/tags/{id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "us-west-2"
    }),
});
const data = await response.json();

Response

200400422

{
  "id": "96cbc789-5a03-4110-abeb-67f5d4f65323",
  "name": "us-west-1",
  "network": "holesky",
  "organizationId": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
  "createdBy": "467c1246-be63-40c2-82c3-10f80d3238bb",
  "createdAt": "2024-03-31T18:13:27.584133"
}

---

Get all validators in a tag

This endpoint allows you to get all the validators associated with a tag. It returns a paginated list of pubkeys along with their metadata.

GET/tags/{id}/validators

Path parameters

id*Id

Query parameters

Header parameters

Response

200400

Successful Response

Body

application/json

previousPrevious

nextNext

pages*Pages

results*Results

Request

JavaScriptCurlPython

const response = await fetch('/tags/{id}/validators', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "previous": "https://endpoint?limit=10&offset=10",
  "next": "https://endpoint?limit=10&offset=10",
  "pages": 10,
  "results": [
    {
      "validatorPubkey": "0x800...",
      "tagId": "96cbc789-5a03-4110-abeb-67f5d4f65323",
      "tagName": "us-west-1",
      "createdBy": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
      "createdAt": "2024-03-31T18:13:27.584133"
    }
  ]
}

---

Add validators to a tag

This endpoint allows you to add validators to a tag. You must pass an array of validator pubkeys in the body.

POST/tags/{id}/validators

Path parameters

id*Id

Header parameters

Body

application/json

pubkeys*Pubkeys

Response

201400

Successful Response

Body

application/json

validatorPubkey*Validatorpubkey

tagId*Tagid

tagName*Tagname

createdBy*Createdby

createdAt*Createdat

Request

JavaScriptCurlPython

const response = await fetch('/tags/{id}/validators', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "pubkeys": [
        "0x00..",
        "0x01..."
      ]
    }),
});
const data = await response.json();

Response

201400

[
  {
    "validatorPubkey": "0x800...",
    "tagId": "96cbc789-5a03-4110-abeb-67f5d4f65323",
    "tagName": "us-west-1",
    "createdBy": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
    "createdAt": "2024-03-31T18:13:27.584133"
  }
]

---

Remove validator pubkey from a tag

This endpoint allows you to remove a validator from a tag by passing the validator pubkey as a path parameter.

DELETE/tags/{id}/validators/{pubkey}

Path parameters

id*Id

pubkey*Pubkey

Header parameters

Response

204400

Successful Response

Request

JavaScriptCurlPython

const response = await fetch('/tags/{id}/validators/{pubkey}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

400

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}