a4-cli 0.44.2

"""Generated by a4 from protocol package `token-raise` 1.0.0 (arete.protocol-spec/v1 `tokenRaise`). Do not edit.

A token raise on Meteora Presale with a soft cap, team finalisation through Squads, and refunds.
"""

from __future__ import annotations

from typing import Any, Dict, List, Literal, Mapping, NoReturn, Optional, Sequence, TypedDict, Union

import httpx

from arete.auth import AuthConfig
from arete.errors import AreteError
from arete.protocol import (
    ProtocolAccessRejectionCode,
    ProtocolClient,
    ProtocolDefinition,
    ProtocolDeployment,
    ProtocolInstanceHandle,
    ProtocolInteger,
    ProtocolLiveStack,
    ProtocolMetadataFieldDefinition,
    ProtocolPrepared,
    ProtocolRejection,
    ProtocolStateRejectionCode,
    ProtocolStepDefinition,
    ProtocolTransactionFormat,
    VerifiedWebhook,
    decimal_args,
    verify_webhook,
)
from .stacks import meteora_presale as _meteora_presale_stack
from .stacks import mirror as _mirror_stack
from .programs import squads_v4 as _squads_v4_program

TokenRaiseInstanceState = Literal["awaiting_approval", "closed", "failed", "finalized", "open", "succeeded"]
TokenRaiseParticipantState = Literal["claimed", "contributed", "refunded"]
TokenRaiseEvent = Literal["contribution.confirmed", "raise.failed", "raise.succeeded"]


class TokenRaiseParams(TypedDict):
    deadline: ProtocolInteger
    hardCap: ProtocolInteger
    quoteMint: str
    softCap: ProtocolInteger
    walletCap: ProtocolInteger


class TokenRaiseClaimArgs(TypedDict):
    pass


TokenRaiseClaimGuardCode = Literal["raise_not_finalized"]


TokenRaiseClaimResult = Union[ProtocolPrepared, ProtocolRejection[Union[TokenRaiseClaimGuardCode, ProtocolAccessRejectionCode, ProtocolStateRejectionCode]]]


class TokenRaiseContributeArgs(TypedDict):
    amount: ProtocolInteger


TokenRaiseContributeGuardCode = Literal["deadline_passed", "hard_cap_exceeded", "raise_not_open", "wallet_cap_exceeded"]


TokenRaiseContributeResult = Union[ProtocolPrepared, ProtocolRejection[Union[TokenRaiseContributeGuardCode, ProtocolAccessRejectionCode, ProtocolStateRejectionCode]]]


class TokenRaiseCreateArgs(TypedDict):
    deadline: ProtocolInteger
    hardCap: ProtocolInteger
    members: List[str]
    quoteMint: str
    softCap: ProtocolInteger
    walletCap: ProtocolInteger


TokenRaiseCreateGuardCode = Literal["soft_cap_above_hard_cap"]


TokenRaiseCreateResult = Union[ProtocolPrepared, ProtocolRejection[Union[TokenRaiseCreateGuardCode, ProtocolAccessRejectionCode, ProtocolStateRejectionCode]]]


class TokenRaiseRefundArgs(TypedDict):
    pass


TokenRaiseRefundGuardCode = Literal["raise_not_failed"]


TokenRaiseRefundResult = Union[ProtocolPrepared, ProtocolRejection[Union[TokenRaiseRefundGuardCode, ProtocolAccessRejectionCode, ProtocolStateRejectionCode]]]


class TokenRaiseInstanceMetadata(TypedDict, total=False):
    name: str
    tagline: str
    ticker: str


class TokenRaiseParticipantMetadata(TypedDict):
    pass


class TokenRaiseWebhookPayload(TypedDict):
    """The JSON body of a `tokenRaise` webhook delivery."""

    id: str
    event: TokenRaiseEvent
    deploymentId: str
    instanceId: str
    participantId: Optional[str]
    state: Union[TokenRaiseInstanceState, TokenRaiseParticipantState]
    occurredAt: str


STACKS: Dict[str, Any] = {
    "meteoraPresale": _meteora_presale_stack.ORE_STREAM_STACK,
    "mirror": _mirror_stack.ORE_STREAM_STACK,
}
PROGRAMS: Dict[str, Any] = {
    "meteoraPresale": _meteora_presale_stack.ORE_STREAM_STACK.programs["ore"],
    "squadsV4": _squads_v4_program.PROGRAMS["vote_program"],
}

TOKEN_RAISE_PROTOCOL: ProtocolDefinition = ProtocolDefinition(
    name="tokenRaise",
    version="1.0.0",
    package="token-raise",
    package_release_hash="arete:registry-package-release:v2:sha256:9999999999999999999999999999999999999999999999999999999999999999",
    protocol_spec_hash="arete:h1:protocol-spec:sha256:29f83127858da49a1eb9308c1986319ea71180eb1bdcd85567d52f31b6c719a0",
    protocol_release_hash="arete:h1:protocol-release:sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
    deployment=ProtocolDeployment(
        deployment_id="7d0c5a52-2f8e-4c1b-9a37-1b6f3c2a9e10",
        access="public",
        api_url="https://api.example.test/api",
        session_endpoint="https://api.example.test/ws/sessions",
    ),
    instance_visibility="account",
    steps={
        "claim": ProtocolStepDefinition(scope="participant", access="public", guards=("raise_not_finalized",), args=()),
        "contribute": ProtocolStepDefinition(scope="participant", access="public", guards=("raise_not_open", "deadline_passed", "wallet_cap_exceeded", "hard_cap_exceeded"), args=("amount",)),
        "create": ProtocolStepDefinition(scope="create", access="secret", guards=("soft_cap_above_hard_cap",), args=("deadline", "hardCap", "members", "quoteMint", "softCap", "walletCap")),
        "refund": ProtocolStepDefinition(scope="participant", access="public", guards=("raise_not_failed",), args=()),
    },
    events={
        "contribution.confirmed": "participant",
        "raise.failed": "instance",
        "raise.succeeded": "instance",
    },
    instance_metadata={
        "name": ProtocolMetadataFieldDefinition(writer="creator", filterable=True),
        "tagline": ProtocolMetadataFieldDefinition(writer="creator", filterable=False),
        "ticker": ProtocolMetadataFieldDefinition(writer="creator", filterable=True),
    },
    stacks=STACKS,
    programs=PROGRAMS,
)


class TokenRaisePublicSteps:
    """Steps a publishable key may prepare."""

    def __init__(self, client: ProtocolClient) -> None:
        self._client = client

    async def claim(
        self,
        *,
        instance: str,
        wallet: str,
        args: Optional[TokenRaiseClaimArgs] = None,
        transaction_format: ProtocolTransactionFormat = "v1",
        idempotency_key: Optional[str] = None,
        client_context: Optional[Mapping[str, Any]] = None,
    ) -> TokenRaiseClaimResult:
        """Prepare `claim` (participant step, public access)."""
        return await self._client.prepare(
            "claim",
            wallet=wallet,
            instance=instance,
            args=args,
            transaction_format=transaction_format,
            idempotency_key=idempotency_key,
            client_context=client_context,
        )

    async def contribute(
        self,
        *,
        instance: str,
        wallet: str,
        args: TokenRaiseContributeArgs,
        transaction_format: ProtocolTransactionFormat = "v1",
        idempotency_key: Optional[str] = None,
        client_context: Optional[Mapping[str, Any]] = None,
    ) -> TokenRaiseContributeResult:
        """Contribute. Prepare `contribute` (participant step, public access)."""
        return await self._client.prepare(
            "contribute",
            wallet=wallet,
            instance=instance,
            args=decimal_args(args, ("amount",)),
            transaction_format=transaction_format,
            idempotency_key=idempotency_key,
            client_context=client_context,
        )

    async def refund(
        self,
        *,
        instance: str,
        wallet: str,
        args: Optional[TokenRaiseRefundArgs] = None,
        transaction_format: ProtocolTransactionFormat = "v1",
        idempotency_key: Optional[str] = None,
        client_context: Optional[Mapping[str, Any]] = None,
    ) -> TokenRaiseRefundResult:
        """Prepare `refund` (participant step, public access)."""
        return await self._client.prepare(
            "refund",
            wallet=wallet,
            instance=instance,
            args=args,
            transaction_format=transaction_format,
            idempotency_key=idempotency_key,
            client_context=client_context,
        )


class TokenRaiseSecretSteps(TokenRaisePublicSteps):
    """Every client-callable step; `secret` steps need a secret key."""

    async def create(
        self,
        *,
        wallet: str,
        args: TokenRaiseCreateArgs,
        transaction_format: ProtocolTransactionFormat = "v1",
        idempotency_key: Optional[str] = None,
        client_context: Optional[Mapping[str, Any]] = None,
    ) -> TokenRaiseCreateResult:
        """Create a launch. Prepare `create` (create step, secret access)."""
        return await self._client.prepare(
            "create",
            wallet=wallet,
            args=decimal_args(args, ("deadline", "hardCap", "softCap", "walletCap")),
            transaction_format=transaction_format,
            idempotency_key=idempotency_key,
            client_context=client_context,
        )


class TokenRaiseClient(ProtocolClient):
    """`tokenRaise` with a publishable key (`AuthConfig(publishable_key=...)`): only
    `public` steps are on `steps`.

    `prepare_steps` limits which steps the session may prepare (default:
    every `public` step).
    """

    steps: TokenRaisePublicSteps

    def __init__(
        self,
        *,
        auth: Optional[AuthConfig] = None,
        http_client: Optional[httpx.AsyncClient] = None,
        api_url: Optional[str] = None,
        session_endpoint: Optional[str] = None,
        deployment_id: Optional[str] = None,
        stacks: Optional[Mapping[str, Any]] = None,
        programs: Optional[Mapping[str, Any]] = None,
        key_class: Optional[str] = None,
        prepare_steps: Optional[Sequence[str]] = None,
    ) -> None:
        super().__init__(
            TOKEN_RAISE_PROTOCOL,
            auth=auth,
            http_client=http_client,
            api_url=api_url,
            session_endpoint=session_endpoint,
            deployment_id=deployment_id,
            stacks=stacks,
            programs=programs,
            key_class=key_class,
            steps=prepare_steps,
        )
        self.steps = TokenRaisePublicSteps(self)

    @classmethod
    def from_session(
        cls, session: Any, *, prepare_steps: Optional[Sequence[str]] = None
    ) -> "TokenRaiseClient":
        """A client on `session`'s auth and HTTP client whose instance handles
        follow the session's connected stacks."""
        return cls(**session.protocol_client_options(TOKEN_RAISE_PROTOCOL), prepare_steps=prepare_steps)

    def instance_handle(
        self, instance_id: str, *, wallet: Optional[str] = None
    ) -> ProtocolInstanceHandle:
        """A live instance, kept current from its event stream; use it with
        `async with` or `await` it.

        This protocol publishes no live stack view.
        """
        return super().instance_handle(instance_id, wallet=wallet)


class TokenRaiseSecretClient(ProtocolClient):
    """`tokenRaise` with a secret key (`AuthConfig(secret_key=...)`, or `ARETE_API_KEY`):
    every client-callable step is on `steps`. Raises when the configured
    credential is a publishable key.
    """

    steps: TokenRaiseSecretSteps

    def __init__(
        self,
        *,
        auth: Optional[AuthConfig] = None,
        http_client: Optional[httpx.AsyncClient] = None,
        api_url: Optional[str] = None,
        session_endpoint: Optional[str] = None,
        deployment_id: Optional[str] = None,
        stacks: Optional[Mapping[str, Any]] = None,
        programs: Optional[Mapping[str, Any]] = None,
    ) -> None:
        super().__init__(
            TOKEN_RAISE_PROTOCOL,
            auth=auth,
            http_client=http_client,
            api_url=api_url,
            session_endpoint=session_endpoint,
            deployment_id=deployment_id,
            stacks=stacks,
            programs=programs,
            key_class="secret",
        )
        if self.key_class != "secret":
            raise AreteError(
                "TokenRaiseSecretClient requires a secret key; use TokenRaiseClient with a publishable key",
                "INVALID_CONFIG",
            )
        self.steps = TokenRaiseSecretSteps(self)

    @classmethod
    def from_session(cls, session: Any) -> "TokenRaiseSecretClient":
        """A client on `session`'s auth and HTTP client whose instance handles
        follow the session's connected stacks."""
        options = session.protocol_client_options(TOKEN_RAISE_PROTOCOL)
        options.pop("key_class", None)
        return cls(**options)

    def instance_handle(
        self, instance_id: str, *, wallet: Optional[str] = None
    ) -> ProtocolInstanceHandle:
        """A live instance, kept current from its event stream; use it with
        `async with` or `await` it.

        This protocol publishes no live stack view.
        """
        return super().instance_handle(instance_id, wallet=wallet)


def verify_token_raise_webhook(
    secret: Union[str, bytes],
    body: Union[str, bytes],
    headers: Any,
    *,
    now: Optional[int] = None,
    tolerance_seconds: int = 300,
) -> VerifiedWebhook[TokenRaiseWebhookPayload]:
    """Verify a signed webhook delivery for this protocol's events."""
    return verify_webhook(secret, body, headers, now=now, tolerance_seconds=tolerance_seconds)


__all__ = [
    "TOKEN_RAISE_PROTOCOL",
    "TokenRaiseClient",
    "TokenRaiseSecretClient",
    "TokenRaisePublicSteps",
    "TokenRaiseSecretSteps",
    "TokenRaiseInstanceState",
    "TokenRaiseParticipantState",
    "TokenRaiseEvent",
    "TokenRaiseParams",
    "TokenRaiseInstanceMetadata",
    "TokenRaiseParticipantMetadata",
    "TokenRaiseWebhookPayload",
    "STACKS",
    "PROGRAMS",
    "verify_token_raise_webhook",
    "TokenRaiseClaimArgs",
    "TokenRaiseClaimGuardCode",
    "TokenRaiseClaimResult",
    "TokenRaiseContributeArgs",
    "TokenRaiseContributeGuardCode",
    "TokenRaiseContributeResult",
    "TokenRaiseCreateArgs",
    "TokenRaiseCreateGuardCode",
    "TokenRaiseCreateResult",
    "TokenRaiseRefundArgs",
    "TokenRaiseRefundGuardCode",
    "TokenRaiseRefundResult",
]