# Shield

> Deploy and close a license's private copy of the Proxima on-chain program on Solana.

A Shield is a per-license copy of the Proxima on-chain program (OCP) on Solana, deployed by one of the license's funders. Once deployed, its program id is returned as `custom_ocp`.

Deploying is paid by a funder that must hold at least 7 SOL (`ocp.minimum_funder_balance` in the [constants](/reference/platform/#object-constants)). Closing the Shield closes its program accounts, reclaims their rent and resets the license. Shield is Solana-only: `{chain_id}` must be `sol`.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `GET /{chain_id}/shield/get-shield-info`: Retrieve the Shield
- `POST /{chain_id}/shield/deploy`: Deploy a Shield
- `POST /{chain_id}/shield/close`: Close the Shield

## The Shield object

The Shield state of the license.

- `custom_ocp` (string | null): Program id of the license's deployed Shield, or `null` when none is deployed.
- `status` (enum): Deployment state. Possible values: `None`, `Pending`, `Failed`, `Deployed`.
- `deployer_pubkey` (string | null): Funder that deployed the Shield and is the only one able to close it, or `null`.

```json
{
  "custom_ocp": "Px9mKc3TqWv7Ra2YbHn5DsLf8GzJe4Uu6Nt1Qw3Ek2B",
  "status": "Deployed",
  "deployer_pubkey": "DkR4mWq7TzY2bNc9HvJ3sLp8XfGa5Ue6Kt1Qw2Ey4Mh"
}
```

### Retrieve the Shield

`GET /{chain_id}/shield/get-shield-info`

Returns the Shield state of the license. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The Shield settings badge polls this every 20 seconds, and the Shield dialog every 5 seconds while open.

#### Path parameters

- `chain_id` (enum, required): Chain id. Shield is Solana-only; any other value is rejected. Possible values: `sol`.

#### Returns 200 OK

Returns a [Shield](#object-shield) object.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `this endpoint only supports sol, got <chain_id>` | `{chain_id}` is not `sol`. An unknown chain id gets `unknown chain_id: <chain_id>`. | Call it with `sol`. |
| 404 | `not_found` | `Couldn't find shield info` | The license's Shield information could not be read. | Retry after a few seconds. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/sol/shield/get-shield-info" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "custom_ocp": "Px9mKc3TqWv7Ra2YbHn5DsLf8GzJe4Uu6Nt1Qw3Ek2B",
  "status": "Deployed",
  "deployer_pubkey": "DkR4mWq7TzY2bNc9HvJ3sLp8XfGa5Ue6Kt1Qw2Ey4Mh"
}
```

### Deploy a Shield

`POST /{chain_id}/shield/deploy`

Deploys the license's Shield, paid by one of its funders. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. Read `status` with [Retrieve the Shield](/reference/shield/#retrieve-shield) first: `Deployed` means the first call went through, `Pending` that it is still running. Deploying again while `Pending` pays for a second program.

The status is `Pending` while the deployment runs, then `Deployed`, or `Failed` on error. The request returns when the deployment has finished. The web app lets the user pick the paying funder and requires it to hold at least 7 SOL.

> Spends SOL from the funder for the on-chain deployment.

#### Path parameters

- `chain_id` (enum, required): Chain id. Shield is Solana-only; any other value is rejected. Possible values: `sol`.

#### Body parameters

- `funder_pubkey` (string, optional): Funder that pays for the deployment. Omit to use the license's default funder, but still send a JSON body (`{}`): a request without a body is rejected.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `message` (string): Result message.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `this endpoint only supports sol, got <chain_id>` | `{chain_id}` is not `sol`. An unknown chain id gets `unknown chain_id: <chain_id>`. | Call it with `sol`. |
| 409 | `conflict` | `On chain program already deployed` | The license already has a deployed program. | Use the deployed program, or close it with [Close the Shield](/reference/shield/#close-shield) before deploying again. |
| 422 | `unprocessable` | `Funder doesn't have enough balance` | The funder holds less than the minimum balance (7 SOL). | Fund it with at least 7 SOL, or pick another funder from [List funders](/reference/funders/#list-funders). |
| 422 | `upstream_failure` | `rpc api issue: <reason>` | The funder's balance could not be read from the Solana RPC. Nothing was deployed. | Retry after a few seconds. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/sol/shield/deploy" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "funder_pubkey": "DkR4mWq7TzY2bNc9HvJ3sLp8XfGa5Ue6Kt1Qw2Ey4Mh"
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully deployed ocp"
}
```

### Close the Shield

`POST /{chain_id}/shield/close`

Closes the license's Shield and reclaims the rent of its accounts. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A retry after a successful close returns `404` (`No shield deployer recorded, cannot close`).

> Closing cannot be undone: a new Shield needs a new deployment. Do not remove the deployer funder while the Shield is deployed, or it cannot be closed.

#### Path parameters

- `chain_id` (enum, required): Chain id. Shield is Solana-only; any other value is rejected. Possible values: `sol`.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `message` (string): Result message.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `this endpoint only supports sol, got <chain_id>` | `{chain_id}` is not `sol`. An unknown chain id gets `unknown chain_id: <chain_id>`. | Call it with `sol`. |
| 404 | `not_found` | `No shield deployer recorded, cannot close` | No deployer is recorded: the license has no deployed Shield, or it was already closed. | Check `status` with [Retrieve the Shield](/reference/shield/#retrieve-shield). |
| 404 | `not_found` | `Shield deployer funder not found, do not remove it while shield is deployed` | The funder that deployed the program was removed from the license. Only that funder can close it. | Contact support to close the program. |
| 422 | `upstream_failure` | `tx_engine api issue: Error while closing programs accounts` | The program account is still open after the close transactions. The Shield stays recorded as deployed. | Retry; only the accounts still open are closed again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/sol/shield/close" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully closed programs"
}
```
