Skip to content

docs(bounty): align guides with chat and snapshot scoring #27

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.

Sign up for GitHub

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

Merged
Mathis (echobt) merged 2 commits into from
Sep 19, 2026
Merged

docs(bounty): align guides with chat and snapshot scoring #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
308c483
docs(bounty): align guides with chat and snapshot scoring
echobt Sep 19, 2026
91719fe
docs(bounty): explain explicit research terms consent
echobt Sep 19, 2026
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
89 changes: 22 additions & 67 deletions bounty/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,97 +1,52 @@
---
title: "Cortex Bounty"
description: "The Cortex Bounty Challenge: pair a mining hotkey, file a report from Chat, and read every verdict on a public log"
description: "Find Cortex Bounty in Chat, link a mining hotkey, submit a useful finding, and verify published verdicts and scoring."
icon: "coins"
---

Cortex Bounty is the **Cortex Bounty Challenge**, a bug bounty for miners on the Cortex subnet. You pair a mining hotkey to a Cortex account, look for a real defect in Cortex inside a marked conversation, file a report, and wait for a verdict. Every verdict that is reached is published on a log that anyone can read without signing in and without a credential.
Cortex Bounty rewards useful, reproducible vulnerability reports about Cortex. Cortex records hotkey links and adjudicates findings; the subnet reads the public findings to calculate weights. Filing a report, receiving a valid verdict and receiving an on-chain reward are separate steps.

Cortex plays three parts in the programme: it records your pairing and the session context, it adjudicates the reports that are filed, and it publishes the public transparency log. It does not set weights and it does not compute a score. The subnet reads the public endpoints and sets weights from the valid rows it finds there.
## Where to find Bounty

## The four pages of this section
Open [Cortex Chat](https://app.cortex.foundation) with a **dedicated mining account**. Bounty is a programme inside Cortex, not a separate application or a page at `/bounty` in the app.

- **Link a hotkey:** send `/link <ss58>` in Chat and complete the signing card.
- **File a finding:** open **Settings > General > Report a bug**, then **Add to the Challenge Bounty** on the receipt when your report is eligible.
- **Read published findings:** use the [Transparency API](/bounty/public-api). Its leaderboard is a public JSON response, not a payout dashboard.

<Warning>
Linking requires explicit acceptance of the current research terms. Read the terms card before accepting, then request the signing card. Sending `/link` alone does not accept anything or link a key. See [Pair a hotkey](/bounty/pair-a-hotkey), including what to do if your app does not yet show an acceptance control.
</Warning>

## Participate

<CardGroup cols={2}>
<Card title="Pair a hotkey" icon="key" href="/bounty/pair-a-hotkey">
Accept the terms, sign the payload the CLI prints, and link an SS58 hotkey to your mining account.
Check the prerequisites and sign a Chat card with your mining hotkey.
</Card>
<Card title="File a report" icon="flag" href="/bounty/report">
Mark a conversation as a miner session, file from Chat, and see what the report carries.
Submit a reproducible finding and add an eligible bug report to Bounty.
</Card>
<Card title="Verdicts and scoring" icon="scale-balanced" href="/bounty/scoring">
The four statuses, the gates a row has to clear, and what can never become a valid row.
Understand severity, eligibility and why a valid report is not a guaranteed payment.
</Card>
<Card title="Transparency API" icon="globe" href="/bounty/public-api">
The unauthenticated public endpoints, windows and paging, and how to read a zero.
Read the public status, leaderboard and reports from one consistent publication.
</Card>
</CardGroup>

## Before you start

Use a **dedicated mining** Cortex account, not your private personal account. The programme terms are explicit about why: "Conversations, logs, and the account may be read for research, to fix bugs, and to remunerate you."

<Warning>
Accepting the terms is blocking. Until the terms are accepted, pairing is refused and so is marking a conversation as a miner session. The version in force is `bounty-research-v1`, and what is stored with your acceptance is your account id, that version, and a timestamp.
</Warning>

## How it flows end to end

<Steps>
<Step title="Create a dedicated mining account">
Sign in to Cortex with an account you keep for mining. See [Accounts and sign-in](/getting-started/accounts).
</Step>
<Step title="Accept the terms and pair a hotkey">
Install the Cortex CLI and run the pairing command. The CLI prints an exact string, you sign it with your own wallet tool, and the hotkey is linked. Full procedure on [Pair a hotkey](/bounty/pair-a-hotkey).
</Step>
<Step title="Mark a conversation as a miner session">
Pairing prints a command to send in Chat, plus a one-time session code. Sending that command marks the conversation as a bounty-miner session and injects miner context.
</Step>
<Step title="Find a defect and file a report">
Describe what you found in the marked conversation, then file it with the Chat report tool. See [File a report](/bounty/report).
</Step>
<Step title="Wait for a verdict">
A filed report is pending and private. It is not on the public endpoints, and fetching it by id answers as though it did not exist, until a verdict exists.
</Step>
<Step title="Read the verdict on the public log">
Once a verdict is recorded, the row becomes public. Anyone can read it, count it and verify it with the [Transparency API](/bounty/public-api).
</Step>
</Steps>

## What a machine decides and what a person decides

Two different kinds of decision sit in this programme, and it is worth knowing which is which before you file.

| Decided mechanically | Decided by judgement |
| --- | --- |
| Whether the terms are accepted, and therefore whether you may pair or mark a session at all | Whether what you found is a real, unique defect |
| Whether a hotkey is already held by another account | Which of the four statuses your report receives |
| Whether a report has enough substance to be published at all | The wording of the finding and the reasoning recorded with the verdict |
| Whether a row appears on the public endpoints, and in which window | Whether a report duplicates an earlier one, and which one it names |

The mechanical gates are described in full on [Verdicts and scoring](/bounty/scoring). They are the usual reason a report you consider valid has not appeared on the public log.

## What this section does not tell you

This documentation covers the mechanics: pairing, filing, verdicts, and the public log. It does not state what a reward is worth, when a verdict will arrive, or who is eligible to take part. Those belong to the programme's own terms, the ones you accept at pairing, and they can depend on the case. Do not read an amount or a schedule into the three outcomes described on the scoring page.

## How it fits with the other Cortex products

Cortex Bounty is a programme rather than an application you open, so it borrows the surfaces of two products you already have.
## Privacy and rewards

- The [Cortex CLI](/cli/index) does the pairing. It is the only place the pairing command runs, and the only place the string you have to sign is printed.
- [Cortex Chat](/chat/index) is where a report is filed, from a conversation that has been marked as a miner session. The report tool is not offered in an ordinary conversation.
- The Transparency API stands on its own. It needs no account, so a third party can check a payout claim without your help.
Use an account reserved for mining: programme terms allow its conversations and logs to be used for research, fixing defects and assessing rewards. Never submit wallet secrets. The signing card needs a signature, not a seed phrase or private key.

If you have found a defect but are not a miner on the subnet, this is not your intake. Use [Report a bug](/getting-started/report-a-bug) instead.
Pending findings stay private. After adjudication, a public record contains the verdict and its justification, not the original report body or Chat transcript. A public summary appears only when staff approves it.

<Note>
Not part of this programme, and not a Cortex feature: `/miner` is not a command and never will be, there is no attestation surface here, and there is no teacher host. The subnet runs its own pipeline beyond the public log, and nothing in it is documented on this site.
</Note>
Bounty has 20% of subnet emission. Its share is not increased when another challenge is unavailable. Published report counts are not reward weights, and an unavailable scorer can leave the Bounty share unallocated to miners. The [scoring rules](/bounty/scoring) explain the additional eligibility gates. A public verdict alone is not evidence of an on-chain payment.

## Related

- [Pair a hotkey](/bounty/pair-a-hotkey)
- [File a report](/bounty/report)
- [Verdicts and scoring](/bounty/scoring)
- [Transparency API](/bounty/public-api)
- [Install the CLI](/cli/install)
- [Report a bug](/getting-started/report-a-bug)
103 changes: 36 additions & 67 deletions bounty/pair-a-hotkey.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,100 +1,69 @@
---
title: "Pair a hotkey"
description: "Accept the Cortex Bounty terms and link an SS58 mining hotkey to your Cortex account by signing the payload the CLI prints"
description: "Review and accept the Bounty research terms in Chat, then link your mining hotkey by signing the /link card with your wallet."
icon: "key"
---

Pairing is the first thing you do in [Cortex Bounty](/bounty/index). It links a mining hotkey to a Cortex account, so that a report filed from that account can be credited to that hotkey on the public log. Nothing else in the programme works until a hotkey is paired: the Chat report tool is not offered, and a conversation cannot be marked as a miner session.
Pairing links your mining hotkey to your Cortex account so published findings can be credited to it. Start in [Cortex Chat](https://app.cortex.foundation), not in the Cortex CLI. There is no separate Bounty application to open.

Pairing happens entirely in the terminal, with the Cortex CLI. It proves two things at once, that you control the Cortex account and that you control the hotkey, by having you sign a string the CLI prints with your own wallet tool. This page covers what you need, the exact command, what you sign, and how many hotkeys one account may hold.
## Before you start

## What you need

- A **dedicated mining** Cortex account. Reports, conversations and logs on it may be read for research, to fix bugs, and to remunerate you, so do not use a private personal account. See [Accounts and sign-in](/getting-started/accounts).
- The Cortex CLI installed. The binary is `cortex`. See [Install the CLI](/cli/install).
- Your hotkey's SS58 address, and a wallet tool that can sign an arbitrary string with it. **btcli** and **polkadot-js** both do this.
- Use a **dedicated mining account**. Its conversations and logs may be used for research, fixing bugs and assessing rewards. Do not link a private personal account.
- Have your hotkey's SS58 address and a wallet tool that can sign a message with that hotkey.
- Read the current research terms before deciding whether to participate.

<Warning>
Cortex never asks for a mnemonic. The CLI prints a string and asks for a signature over it. Nothing in this flow needs your seed phrase, your private key or a wallet file, and no Cortex surface will ever ask for one.
Sending `/link` does not count as consent. You must explicitly accept the displayed research terms before requesting a signature. If you do not agree, cancel; you can still [report a bug](/getting-started/report-a-bug) without joining Bounty.
</Warning>

## Accept the terms

The terms version in force is `bounty-research-v1`. It is shown to you at pairing, and your acceptance is stored as three things: your account id, that version, and a timestamp.

Acceptance is blocking rather than advisory. Until the terms are accepted, pairing is refused and so is marking a conversation as a miner session. You accept them as part of the pairing command, with `--accept-terms`.

## Pair the hotkey
## Link in Chat

<Steps>
<Step title="Run the pairing command">
Pass the SS58 address of the hotkey you want to link.

```bash
cortex bounty pair --hotkey <ss58> --accept-terms
```
</Step>
<Step title="Sign in with your Cortex account">
The CLI signs you in. If you already have an access token you can supply it to the CLI with `--token` instead of signing in. See [Sign in to the CLI](/cli/sign-in).
</Step>
<Step title="Read the payload the CLI prints">
The CLI asks the challenge backend for a nonce, then prints the exact string to sign. It has four parts separated by a vertical bar: a fixed prefix, your account id, the nonce, and an expiry.
<Step title="Start linking in Chat">
Sign in to your mining account and send this as a Chat message, replacing the placeholder with your public hotkey address:

```text
cortex-bounty-v1|{account_id}|{nonce}|{exp}
/link <ss58>
```

Sign that string exactly as printed, byte for byte. Do not reformat it, do not trim it, and do not sign the address or a hash of your own making.
If the current terms are already accepted, Chat displays the signing card. Otherwise it first offers the research terms.
</Step>
<Step title="Sign it with your wallet tool">
Use **btcli** or **polkadot-js** to sign the string with the hotkey named in the command. The signature is produced entirely on your side.
<Step title="Review the research terms">
Read the displayed title, version and full terms. To participate, select **I have read and accept these terms**, then **Accept terms**. The checkbox starts unchecked. Choose **Cancel** to leave without accepting.

After the accepted confirmation, send the same `/link` message again to request the signing card. Accepting terms does not link your key or sign anything for you.
</Step>
<Step title="Return the signature to the CLI">
Hand the signature back to the CLI. When it is accepted, the hotkey is linked to the account and pairing is done.
<Step title="Sign locally with your hotkey">
Check the address on the card. Use your wallet tool to sign the complete displayed message, without editing it, using that hotkey rather than your coldkey.
</Step>
<Step title="Keep what the CLI prints next">
Pairing prints two things you need in Chat: the command that marks a conversation as a miner session, and a one-time session code. Keep both. The command is a secret and must not be shared or posted anywhere.
<Step title="Submit only the signature">
Paste the hexadecimal signature into the card and submit it. Wait for the linked confirmation before filing a Bounty report.
</Step>
</Steps>

## What pairing gives you

| What you get | What it is for |
| --- | --- |
| A linked hotkey | Reports filed from this account can be credited to this hotkey |
| An accepted terms record | Unblocks pairing and the miner session marking |
| The Chat command | Marks a conversation as a bounty-miner session. See [File a report](/bounty/report) |
| A one-time session code | An optional argument, sent in Chat straight after that command |

The Chat command is configured by an operator, which is why the CLI prints it for you rather than this page naming it. Treat it as a credential: anyone holding it can mark a conversation. `/miner` is not that command, is not a command at all, and never will be.

## Many hotkeys per account, one account per hotkey
<Warning>
Never paste a seed phrase, mnemonic, private key or wallet file into Chat or the signing card. The card accepts only a signature. Signing happens in your wallet.
</Warning>

One Cortex account can hold as many hotkeys as you pair to it. Run the command again with another SS58 for each one.
## If linking is refused

The reverse does not hold. A hotkey belongs to exactly one account, and a second account cannot claim a hotkey that is already paired. The practical consequence is worth stating plainly: **you cannot move a hotkey between accounts by pairing it again elsewhere.** Decide which account is your mining account before you pair, because pairing is not a way to migrate one later.
| What you see | What to do |
| --- | --- |
| Sign-in required | Sign in to the dedicated mining account first. |
| Research terms required | Read the terms card and explicitly accept if you agree, then send `/link` again. |
| Terms changed or acceptance failed | Read the error and reload the current terms. A changed version needs a fresh decision; do not assume acceptance succeeded. |
| Invalid hotkey | Check that you supplied the public SS58 address of the intended hotkey. |
| Hotkey already linked elsewhere | Use the account that owns the link, or another hotkey. Repeating `/link` does not transfer ownership. |
| Invalid, expired or already-used signature request | Send `/link` again and sign the new card's exact message with the matching hotkey. |

## If pairing does not go through
One account can link multiple hotkeys; each hotkey belongs to only one account. Repeat the Chat flow for each key. Linking does not register a miner on the subnet, submit a chain transaction, activate a miner conversation or guarantee a reward. Continue with [File a report](/bounty/report).

<AccordionGroup>
<Accordion title="The command refuses before it prints anything to sign">
The usual cause is the terms. Pairing is refused until `bounty-research-v1` is accepted, which is what `--accept-terms` does. Run the command with that flag.
</Accordion>
<Accordion title="The hotkey is reported as already held">
That hotkey is paired to another Cortex account. Nothing you can do from this account changes that, and a second claim is refused by design. Use a hotkey that is not yet paired, or sign in to the account that holds it.
</Accordion>
<Accordion title="The signature is rejected">
The string has to be signed exactly as printed, and the payload carries an expiry as its last part. If that expiry has passed, run the pairing command again and sign the new payload without editing it. Check also that you signed with the hotkey named in the command rather than another key in your wallet.
</Accordion>
<Accordion title="An error card or a problem code comes back">
Every Cortex failure has one shape and a stable code, and it carries a reference id that is safe to quote. See [Errors](/reference/errors).
</Accordion>
</AccordionGroup>
If your app shows only a terms-required message without an acceptance control, that deployment cannot complete this onboarding flow yet. Do not bypass the consent check or provide a wallet secret to resolve it.

## Related

- [Cortex Bounty](/bounty/index)
- [File a report](/bounty/report)
- [Verdicts and scoring](/bounty/scoring)
- [Install the CLI](/cli/install)
- [Sign in to the CLI](/cli/sign-in)
- [Accounts and sign-in](/getting-started/accounts)
- [Errors](/reference/errors)
Loading
Loading