lightning-terminal/litrpc/lit-autopilot.swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "lit-autopilot.proto",
    "version": "version not set"
  },
  "tags": [
    {
      "name": "Autopilot"
    }
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/v1/autopilot/features": {
      "get": {
        "summary": "litcli: `autopilot features`\nListAutopilotFeatures fetches all the features supported by the Autopilot\nserver along with the rules that we need to support in order to subscribe\nto those features.",
        "operationId": "Autopilot_ListAutopilotFeatures",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/litrpcListAutopilotFeaturesResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "tags": [
          "Autopilot"
        ]
      }
    },
    "/v1/autopilot/sessions": {
      "get": {
        "summary": "litcli: `autopilot list`\nListAutopilotSessions lists all the sessions that are of type\nTypeAutopilot.",
        "operationId": "Autopilot_ListAutopilotSessions",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/litrpcListAutopilotSessionsResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "tags": [
          "Autopilot"
        ]
      },
      "post": {
        "summary": "litcli: `autopilot add`\nAddAutopilotSession creates a new LNC session and attempts to register it\nwith the Autopilot server.",
        "operationId": "Autopilot_AddAutopilotSession",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/litrpcAddAutopilotSessionResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/litrpcAddAutopilotSessionRequest"
            }
          }
        ],
        "tags": [
          "Autopilot"
        ]
      }
    },
    "/v1/autopilot/sessions/{local_public_key}": {
      "delete": {
        "summary": "litcli: `autopilot revoke`\nRevokeAutopilotSession revokes an Autopilot session.",
        "operationId": "Autopilot_RevokeAutopilotSession",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/litrpcRevokeAutopilotSessionResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "local_public_key",
            "description": "The local static public key of the Autopilot session to be revoked.\nWhen using REST, this field must be encoded as base64url.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "byte"
          }
        ],
        "tags": [
          "Autopilot"
        ]
      }
    }
  },
  "definitions": {
    "litrpcAddAutopilotSessionRequest": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string",
          "description": "A human readable label to assign to the session."
        },
        "expiry_timestamp_seconds": {
          "type": "string",
          "format": "uint64",
          "description": "The unix timestamp at which this session should be revoked."
        },
        "mailbox_server_addr": {
          "type": "string",
          "description": "The address of the mailbox server to connect to for this session."
        },
        "dev_server": {
          "type": "boolean",
          "description": "Set to true if tls should be skipped for when connecting to the mailbox."
        },
        "features": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/litrpcFeatureConfig"
          },
          "description": "The features that the session should subscribe to. Each feature maps to\na FeatureConfig that should be applied to that feature."
        },
        "session_rules": {
          "$ref": "#/definitions/litrpcRulesMap",
          "description": "Rules that apply to the entire session. By default, no rules will apply\nto the entire session."
        },
        "no_privacy_mapper": {
          "type": "boolean",
          "description": "Set to true of the session should not make use of the privacy mapper."
        },
        "linked_group_id": {
          "type": "string",
          "format": "byte",
          "description": "Set to the ID of the group to link this session to, if any."
        },
        "privacy_flags": {
          "type": "string",
          "format": "uint64",
          "description": "The privacy flags used by this session. If set, then privacy_flags_set must\nbe set."
        },
        "privacy_flags_set": {
          "type": "boolean",
          "description": "Indicates whether privacy flags are set."
        }
      }
    },
    "litrpcAddAutopilotSessionResponse": {
      "type": "object",
      "properties": {
        "session": {
          "$ref": "#/definitions/litrpcSession",
          "description": "Details of the session that was just created."
        }
      }
    },
    "litrpcChannelConstraint": {
      "type": "object",
      "properties": {
        "min_capacity_sat": {
          "type": "string",
          "format": "uint64",
          "description": "The minimum channel size autopilot has to set for a channel."
        },
        "max_capacity_sat": {
          "type": "string",
          "format": "uint64",
          "description": "The maximum channel size autopilot can set for a channel."
        },
        "max_push_sat": {
          "type": "string",
          "format": "uint64",
          "description": "The maximum push amount for a channel."
        },
        "private_allowed": {
          "type": "boolean",
          "description": "Indicates whether opening of private channels is allowed."
        },
        "public_allowed": {
          "type": "boolean",
          "description": "Indicates whether opening of public channels is allowed."
        }
      }
    },
    "litrpcChannelPolicyBounds": {
      "type": "object",
      "properties": {
        "min_base_msat": {
          "type": "string",
          "format": "uint64",
          "description": "The minimum base fee in msat that the autopilot can set for a channel."
        },
        "max_base_msat": {
          "type": "string",
          "format": "uint64",
          "description": "The maximum base fee in msat that the autopilot can set for a channel."
        },
        "min_rate_ppm": {
          "type": "integer",
          "format": "int64",
          "description": "The minimum ppm fee in msat that the autopilot can set for a channel."
        },
        "max_rate_ppm": {
          "type": "integer",
          "format": "int64",
          "description": "The maximum ppm fee in msat that the autopilot can set for a channel."
        },
        "min_cltv_delta": {
          "type": "integer",
          "format": "int64",
          "description": "The minimum cltv delta that the autopilot may set for a channel."
        },
        "max_cltv_delta": {
          "type": "integer",
          "format": "int64",
          "description": "The maximum cltv delta that the autopilot may set for a channel."
        },
        "min_htlc_msat": {
          "type": "string",
          "format": "uint64",
          "description": "The minimum htlc msat that the autopilot may set for a channel."
        },
        "max_htlc_msat": {
          "type": "string",
          "format": "uint64",
          "description": "The maximum htlc msat that the autopilot may set for a channel."
        }
      }
    },
    "litrpcChannelRestrict": {
      "type": "object",
      "properties": {
        "channel_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uint64"
          },
          "description": "A list of channel IDs that the Autopilot should _not_ perform any actions\non."
        }
      }
    },
    "litrpcFeature": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name is the name of the Autopilot feature."
        },
        "description": {
          "type": "string",
          "description": "A human readable description of what the feature offers."
        },
        "rules": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/litrpcRuleValues"
          },
          "description": "A map of rules that make sense for this feature. Each rule is accompanied\nwith appropriate default values for the feature along with minimum and\nmaximum values for the rules."
        },
        "permissions_list": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/litrpcPermissions"
          },
          "description": "A list of URI permissions required by the feature."
        },
        "requires_upgrade": {
          "type": "boolean",
          "description": "A boolean indicating if the user would need to upgrade their Litd version in\norder to subscribe to the Autopilot feature. This will be true if the\nfeature rules set contains a rule that Litd is unaware of."
        },
        "default_config": {
          "type": "string",
          "description": "The JSON-marshaled representation of a feature's default configuration."
        },
        "privacy_flags": {
          "type": "string",
          "format": "uint64",
          "description": "This feature may require relaxed privacy obfuscation that can be enabled\nwith these flags."
        }
      }
    },
    "litrpcFeatureConfig": {
      "type": "object",
      "properties": {
        "rules": {
          "$ref": "#/definitions/litrpcRulesMap",
          "description": "The RulesMap acts as an override map. In other words, by default the rules\nvalues recommended by the Auto Pilot server will be used but the RulesMap\ncan be used to override the defaults."
        },
        "config": {
          "type": "string",
          "format": "byte",
          "description": "Serialised configuration for the feature."
        }
      }
    },
    "litrpcHistoryLimit": {
      "type": "object",
      "properties": {
        "start_time": {
          "type": "string",
          "format": "uint64",
          "description": "The absolute unix timestamp in seconds before which no information should\nbe shared. This should only be set if duration is not set."
        },
        "duration": {
          "type": "string",
          "format": "uint64",
          "description": "The maximum relative duration in seconds that a request is allowed to query\nfor. This should only be set if start_time is not set."
        }
      }
    },
    "litrpcListAutopilotFeaturesResponse": {
      "type": "object",
      "properties": {
        "features": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/litrpcFeature"
          },
          "description": "A map of feature names to Feature objects describing the feature."
        }
      }
    },
    "litrpcListAutopilotSessionsResponse": {
      "type": "object",
      "properties": {
        "sessions": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/litrpcSession"
          },
          "description": "A list of the Autopilot sessions."
        }
      }
    },
    "litrpcMacaroonPermission": {
      "type": "object",
      "properties": {
        "entity": {
          "type": "string",
          "description": "The entity a permission grants access to. If a entity is set to the\n\"uri\" keyword then the action entry should be one of the special cases\ndescribed in the comment for action."
        },
        "action": {
          "type": "string",
          "description": "The action that is granted. If entity is set to \"uri\", then action must\nbe set to either:\n- a particular URI to which access should be granted.\n- a URI regex, in which case access will be granted to each URI that\nmatches the regex.\n- the \"***readonly***\" keyword. This will result in the access being\ngranted to all read-only endpoints."
        }
      }
    },
    "litrpcMacaroonRecipe": {
      "type": "object",
      "properties": {
        "permissions": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/litrpcMacaroonPermission"
          },
          "description": "A list of permissions that should be included in the macaroon."
        },
        "caveats": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "A list of caveats to add to the macaroon."
        }
      }
    },
    "litrpcOffChainBudget": {
      "type": "object",
      "properties": {
        "max_amt_msat": {
          "type": "string",
          "format": "uint64",
          "description": "The maximum amount that can be spent off-chain excluding fees."
        },
        "max_fees_msat": {
          "type": "string",
          "format": "uint64",
          "description": "The maximum amount that can be spent off-chain on fees."
        }
      }
    },
    "litrpcOnChainBudget": {
      "type": "object",
      "properties": {
        "absolute_amt_sats": {
          "type": "string",
          "format": "uint64",
          "description": "The maximum amount that can be spent on-chain including fees."
        },
        "max_sat_per_v_byte": {
          "type": "string",
          "format": "uint64",
          "description": "The maximum amount that can be spent on-chain in fees."
        }
      }
    },
    "litrpcPeerRestrict": {
      "type": "object",
      "properties": {
        "peer_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "A list of peer IDs that the Autopilot should _not_ perform any actions on."
        }
      }
    },
    "litrpcPermissions": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string",
          "description": "The URI in question."
        },
        "operations": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/litrpcMacaroonPermission"
          },
          "description": "A list of the permissions required for this method."
        }
      }
    },
    "litrpcRate": {
      "type": "object",
      "properties": {
        "iterations": {
          "type": "integer",
          "format": "int64",
          "description": "The number of times a call is allowed in num_hours number of hours."
        },
        "num_hours": {
          "type": "integer",
          "format": "int64",
          "description": "The number of hours in which the iterations count takes place over."
        }
      }
    },
    "litrpcRateLimit": {
      "type": "object",
      "properties": {
        "read_limit": {
          "$ref": "#/definitions/litrpcRate",
          "description": "The rate limit for read-only calls."
        },
        "write_limit": {
          "$ref": "#/definitions/litrpcRate",
          "description": "The rate limit for write/execution calls."
        }
      }
    },
    "litrpcRevokeAutopilotSessionResponse": {
      "type": "object"
    },
    "litrpcRuleValue": {
      "type": "object",
      "properties": {
        "rate_limit": {
          "$ref": "#/definitions/litrpcRateLimit"
        },
        "chan_policy_bounds": {
          "$ref": "#/definitions/litrpcChannelPolicyBounds"
        },
        "history_limit": {
          "$ref": "#/definitions/litrpcHistoryLimit"
        },
        "off_chain_budget": {
          "$ref": "#/definitions/litrpcOffChainBudget"
        },
        "on_chain_budget": {
          "$ref": "#/definitions/litrpcOnChainBudget"
        },
        "send_to_self": {
          "$ref": "#/definitions/litrpcSendToSelf"
        },
        "channel_restrict": {
          "$ref": "#/definitions/litrpcChannelRestrict"
        },
        "peer_restrict": {
          "$ref": "#/definitions/litrpcPeerRestrict"
        },
        "channel_constraint": {
          "$ref": "#/definitions/litrpcChannelConstraint"
        }
      }
    },
    "litrpcRuleValues": {
      "type": "object",
      "properties": {
        "known": {
          "type": "boolean",
          "description": "Whether or not the users version of Litd is aware of this rule."
        },
        "defaults": {
          "$ref": "#/definitions/litrpcRuleValue",
          "description": "The default values for the rule that the Autopilot server recommends for\nthe associated feature."
        },
        "min_value": {
          "$ref": "#/definitions/litrpcRuleValue",
          "description": "The minimum sane value for this rule for the associated feature."
        },
        "max_value": {
          "$ref": "#/definitions/litrpcRuleValue",
          "description": "The maximum sane value for this rule for the associated feature."
        }
      }
    },
    "litrpcRulesMap": {
      "type": "object",
      "properties": {
        "rules": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/litrpcRuleValue"
          },
          "description": "A map of rule name to RuleValue. The RuleValue should be parsed based on\nthe name of the rule."
        }
      }
    },
    "litrpcSendToSelf": {
      "type": "object"
    },
    "litrpcSession": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "byte",
          "description": "A unique ID assigned to the session. It is derived from the session\nmacaroon."
        },
        "label": {
          "type": "string",
          "description": "A user assigned label for the session."
        },
        "session_state": {
          "$ref": "#/definitions/litrpcSessionState",
          "description": "The current state that the session is in. This will give an indication of\nif the session is currently usable or not."
        },
        "session_type": {
          "$ref": "#/definitions/litrpcSessionType",
          "description": "The session type. The will given an indication of the restrictions applied\nto the macaroon assigned to the session."
        },
        "expiry_timestamp_seconds": {
          "type": "string",
          "format": "uint64",
          "description": "The time at which the session will automatically be revoked."
        },
        "mailbox_server_addr": {
          "type": "string",
          "description": "The address of the mailbox server that the LNC connection should use."
        },
        "dev_server": {
          "type": "boolean",
          "description": "If set to true, tls will be skipped  when connecting to the mailbox."
        },
        "pairing_secret": {
          "type": "string",
          "format": "byte",
          "description": "The LNC pairing phrase in byte form."
        },
        "pairing_secret_mnemonic": {
          "type": "string",
          "description": "The LNC pairing phrase in mnemonic form."
        },
        "local_public_key": {
          "type": "string",
          "format": "byte",
          "description": "The long term, local static public key used by this node for the LNC\nconnection."
        },
        "remote_public_key": {
          "type": "string",
          "format": "byte",
          "description": "The long term, remote static public key used by the remote party for the\nLNC connection."
        },
        "created_at": {
          "type": "string",
          "format": "uint64",
          "description": "The time at which the session was created."
        },
        "macaroon_recipe": {
          "$ref": "#/definitions/litrpcMacaroonRecipe",
          "description": "The recipe used for creating a macaroon to use with this session. This will\nbe closely linked to the session type."
        },
        "account_id": {
          "type": "string",
          "description": "If the session is for a specific account, then this will be the account ID\nit is associated with."
        },
        "autopilot_feature_info": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/litrpcRulesMap"
          },
          "description": "If this session is for Autopilot use, then this will be the set of features\nthat the session can be used for along with the rules for each feature."
        },
        "revoked_at": {
          "type": "string",
          "format": "uint64",
          "description": "The unix timestamp indicating the time at which the session was revoked.\nNote that this field has not been around since the beginning and so it\ncould be the case that a session has been revoked but that this field\nwill not have been set for that session. Therefore, it is suggested that\nreaders should not assume that if this field is zero that the session is\nnot revoked. Readers should instead first check the session_state field."
        },
        "group_id": {
          "type": "string",
          "format": "byte",
          "description": "The ID of the group of Session's that this Session is linked to. If this\nsession is not linked to any older Session, then this value will be the\nsame as the ID."
        },
        "feature_configs": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Configurations for each individual feature mapping from the feature name to\na JSON-serialized configuration."
        },
        "privacy_flags": {
          "type": "string",
          "format": "uint64",
          "description": "Privacy flags used for the session that determine how the privacy mapper\noperates."
        }
      }
    },
    "litrpcSessionState": {
      "type": "string",
      "enum": [
        "STATE_CREATED",
        "STATE_IN_USE",
        "STATE_REVOKED",
        "STATE_EXPIRED",
        "STATE_RESERVED"
      ],
      "default": "STATE_CREATED"
    },
    "litrpcSessionType": {
      "type": "string",
      "enum": [
        "TYPE_MACAROON_READONLY",
        "TYPE_MACAROON_ADMIN",
        "TYPE_MACAROON_CUSTOM",
        "TYPE_UI_PASSWORD",
        "TYPE_AUTOPILOT",
        "TYPE_MACAROON_ACCOUNT"
      ],
      "default": "TYPE_MACAROON_READONLY"
    },
    "protobufAny": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "rpcStatus": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/protobufAny"
          }
        }
      }
    }
  }
}