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 object
The Shield state of the license.
Attributes
-
custom_ocpstring | nullProgram id of the license's deployed Shield, ornullwhen none is deployed. -
statusenumDeployment state.Possible valuesNonePendingFailedDeployed -
deployer_pubkeystring | nullFunder that deployed the Shield and is the only one able to close it, ornull.
Retrieve the Shield
/{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_idenum RequiredChain id. Shield is Solana-only; any other value is rejected.Possible valuessol
Returns 200 OK · application/json
Returns a Shield object.
Errors
| Status | Code | When 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
/{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
statuswith Retrieve the Shield first:Deployedmeans the first call went through,Pendingthat it is still running. Deploying again whilePendingpays 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_idenum RequiredChain id. Shield is Solana-only; any other value is rejected.Possible valuessol
Body parameters application/json
-
funder_pubkeystring OptionalFunder 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
-
okbooleanAlwaystrue. -
messagestringResult message.
Errors
| Status | Code | When 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
/{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_idenum RequiredChain id. Shield is Solana-only; any other value is rejected.Possible valuessol
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
messagestringResult message.
Errors
| Status | Code | When 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