Skip to content
API Reference

Search is only available in production builds. Try building and previewing the site to test it out locally.

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). Closing the Shield closes its program accounts, reclaims their rent and resets the license. Shield is Solana-only: {chain_id} must be sol.

The Shield state of the license.

Attributes

  • custom_ocp string | null
    Program id of the license's deployed Shield, or null when none is deployed.
  • status enum
    Deployment state.
    Possible values NonePendingFailedDeployed
  • deployer_pubkey string | null
    Funder that deployed the Shield and is the only one able to close it, or null.

Retrieve the Shield

Bearer JWT
GET /{chain_id}/shield/get-shield-info

Returns the Shield state of the license.

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 · application/json

Returns a Shield object.

Errors

StatusCodeWhen and what to do
400 bad_request {chain_id} is not sol. An unknown chain id gets unknown chain_id: <chain_id>. Call it with sol.
404 not_found The license's Shield information could not be read. Retry after a few seconds.

Also the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.shield.getShield(chainId) src/lib/proxima/endpoints/shield.ts

Deploy a Shield

Bearer JWT
POST /{chain_id}/shield/deploy

Deploys the license's Shield, paid by one of its funders.

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 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.

Path parameters

  • chain_id enum Required
    Chain id. Shield is Solana-only; any other value is rejected.
    Possible values sol

Body parameters application/json

  • 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 · application/json

  • ok boolean
    Always true.
  • message string
    Result message.

Errors

StatusCodeWhen and what to do
400 bad_request {chain_id} is not sol. An unknown chain id gets unknown chain_id: <chain_id>. Call it with sol.
409 conflict The license already has a deployed program. Use the deployed program, or close it with Close the Shield before deploying again.
422 unprocessable The funder holds less than the minimum balance (7 SOL). Fund it with at least 7 SOL, or pick another funder from List funders.
422 upstream_failure The funder's balance could not be read from the Solana RPC. Nothing was deployed. Retry after a few seconds.

Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.

Web client proxima.shield.deploy(chainId, funderPubkey) src/lib/proxima/endpoints/shield.ts

Close the Shield

Bearer JWT
POST /{chain_id}/shield/close

Closes the license's Shield and reclaims the rent of its accounts.

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).

Path parameters

  • chain_id enum Required
    Chain id. Shield is Solana-only; any other value is rejected.
    Possible values sol

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • message string
    Result message.

Errors

StatusCodeWhen and what to do
400 bad_request {chain_id} is not sol. An unknown chain id gets unknown chain_id: <chain_id>. Call it with sol.
404 not_found No deployer is recorded: the license has no deployed Shield, or it was already closed. Check status with Retrieve the Shield.
404 not_found 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 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.

Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.

Web client proxima.shield.closeProgram(chainId) src/lib/proxima/endpoints/shield.ts