# Modular Arithmetic Challenge

Competition ID: `modular-arithmetic-challenge`

Use this guide when automating submissions for the Modular Arithmetic Challenge. This competition accepts a pinned external model artifact rather than an uploaded file.

## Endpoint map

Use `competitionId = modular-arithmetic-challenge`.

**Competition endpoints**

| Task | Endpoint | Scope |
| :--- | :--- | :--- |
| Read schema | [`GET /api/public/v1/competitions/modular-arithmetic-challenge`](./api/get-competition.md#modular-arithmetic-challenge) | `competition.read` |
| Check participation | [`GET /api/public/v1/competitions/modular-arithmetic-challenge/me`](./api/get-my-participation.md#modular-arithmetic-challenge) | `competition.read` |
| Create or replace one submission slot | [`POST /api/public/v1/competitions/modular-arithmetic-challenge/submissions`](./api/submit.md#modular-arithmetic-challenge) | `competition.write` |
| Read all current submission slots | [`GET /api/public/v1/competitions/modular-arithmetic-challenge/submissions/mine`](./api/list-my-submissions.md#modular-arithmetic-challenge) | `competition.read` |
| Read slot 1 (legacy) | [`GET /api/public/v1/competitions/modular-arithmetic-challenge/submissions/me`](./api/get-my-submission-legacy.md#modular-arithmetic-challenge) | `competition.read` |
| Read a submission by ID | [`GET /api/public/v1/competitions/modular-arithmetic-challenge/submissions/{submissionId}`](./api/get-submission.md#modular-arithmetic-challenge) | `competition.read` |
| Read leaderboard | [`GET /api/public/v1/competitions/modular-arithmetic-challenge/leaderboard`](./api/get-leaderboard.md#modular-arithmetic-challenge-example) | `competition.read` |
| Read my standing | [`GET /api/public/v1/competitions/modular-arithmetic-challenge/leaderboard/me`](./api/get-my-standing.md#null-example) | `competition.read` |

**Contributor Network endpoints**

| Task | Endpoint | Scope |
| :--- | :--- | :--- |
| Publish a shared model reference | `POST /api/public/v1/contributor-network/items` | `contributor-network.write` |
| Browse shared model references | `GET /api/public/v1/contributor-network/items?competitionId=modular-arithmetic-challenge&kind=model-reference` | `contributor-network.read` |
| Read one shared model reference | `GET /api/public/v1/contributor-network/items/{itemId}` | `contributor-network.read` |

There is no downloadable text body for this competition. [`GET /submissions/{submissionId}/download`](./api/download-submission.md#modular-arithmetic-challenge) returns `NO_DOWNLOAD_FOR_KIND`.

Use the [Modular Arithmetic Challenge Playground guide](../playground/modular-arithmetic-challenge.md) when you want to evaluate a pinned Hugging Face model revision before creating the official competition submission.

## Submission payload

The competition uses `submissionSpec.kind: "model-reference"`.

Read `submissionSpec.limits.maxEntries` before submitting. Modular Arithmetic Challenge currently returns `3`, so the team's current entries may occupy slots `1`, `2`, and `3`.

**Example request body**

```json
{
  "slot": 2,
  "payload": {
    "modelName": "your-team/your-model",
    "commitHash": "0123456789abcdef0123456789abcdef01234567"
  },
  "meta": {
    "description": "Fine-tuned on a modular-arithmetic dataset."
  }
}
```

Payload fields:

- `slot` is optional and defaults to `1`. It must be an integer from `1` through `submissionSpec.limits.maxEntries`.
- `payload.modelName` is required. It must be a Hugging Face model name in `<owner>/<name>` form.
- `payload.commitHash` is required. It must be the full 40-character lowercase hex commit SHA.
- `meta.description` is optional. Use it for a human-readable note in your own submission history.

## Submit

```bash
curl -X POST "https://api.sair.foundation/api/public/v1/competitions/modular-arithmetic-challenge/submissions" \
  -H "Authorization: Bearer $SAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slot": 2,
    "payload": {
      "modelName": "your-team/your-model",
      "commitHash": "0123456789abcdef0123456789abcdef01234567"
    },
    "meta": {
      "description": "Pinned model revision for public evaluation."
    }
  }'
```

The response is a `model-reference` submission record with `submissionId`, `competitionId`, `kind`, `slot`, `payload`, `meta`, `createdAt`, and `updatedAt`. Re-submitting slot `2` replaces only slot `2`; the API does not choose an empty slot automatically.

## Read all current slots

```bash
curl "https://api.sair.foundation/api/public/v1/competitions/modular-arithmetic-challenge/submissions/mine" \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

The collection response uses the same shape even when no entry exists:

```json
{
  "ok": true,
  "data": {
    "items": [
      {
        "submissionId": "sub_01HX0WT...",
        "competitionId": "modular-arithmetic-challenge",
        "kind": "model-reference",
        "slot": 2,
        "payload": {
          "modelName": "your-team/your-model",
          "commitHash": "0123456789abcdef0123456789abcdef01234567"
        },
        "meta": { "description": "Pinned model revision for public evaluation." },
        "createdAt": "2026-05-18T12:34:56Z",
        "updatedAt": "2026-05-20T08:11:02Z"
      }
    ],
    "nextCursor": null
  }
}
```

## Contributor Network

Publishing to the Contributor Network shares `modelName` and `commitHash` with other participants. It does not create, replace, update, or withdraw any official competition submission.

```bash
curl -X POST "https://api.sair.foundation/api/public/v1/contributor-network/items" \
  -H "Authorization: Bearer $SAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "competitionId": "modular-arithmetic-challenge",
    "kind": "model-reference",
    "source": {
      "from": "model-reference",
      "modelName": "your-team/your-model",
      "commitHash": "0123456789abcdef0123456789abcdef01234567"
    },
    "parentContributorNetworkItemId": null,
    "remark": "Model revision for public comparison."
  }'
```

Browse shared Modular Arithmetic Challenge model references:

```bash
curl "https://api.sair.foundation/api/public/v1/contributor-network/items?competitionId=modular-arithmetic-challenge&kind=model-reference" \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

## Workflow

1. Read the competition detail and confirm `submissionSpec.kind` is `model-reference`; use `submissionSpec.limits.maxEntries` to build the slot selector.
2. Optionally evaluate the pinned model revision through the Modular Arithmetic Challenge Playground workflow.
3. Call `/me` and submit only when `canSubmit` is `true`.
4. Choose a slot and submit the pinned model reference with the exact commit hash.
5. Read `/submissions/mine` to confirm all current slots. `/submissions/me` remains a legacy slot-1 read.
6. Optionally publish `modelName` and `commitHash` to the Contributor Network.

See [Competitions](../competitions.md) for the shared endpoint field tables.