syntax = "proto3";

package code.account.v1;

option go_package = "github.com/code-payments/code-protobuf-api/generated/go/account/v1;account";
option java_package = "com.codeinc.gen.account.v1";
option objc_class_prefix = "CPBAccountV1";

import "common/v1/model.proto";
import "transaction/v2/transaction_service.proto";
import "google/protobuf/timestamp.proto";
import "validate/validate.proto";

service Account {
    // IsCodeAccount returns whether an owner account is a Code account. This hints
    // to the client whether the account can be logged in, used for making payments,
    // etc.
    rpc IsCodeAccount(IsCodeAccountRequest) returns (IsCodeAccountResponse);

    // GetTokenAccountInfos returns token account metadata relevant to the Code owner
    // account.
    rpc GetTokenAccountInfos(GetTokenAccountInfosRequest) returns (GetTokenAccountInfosResponse);
}

message IsCodeAccountRequest {
    // The owner account to check against.
    common.v1.SolanaAccountId owner = 1 [(validate.rules).message.required = true];

    // The signature is of serialize(IsCodeAccountRequest) without this field set
    // using the private key of the owner account. This provides an authentication
    // mechanism to the RPC.
    common.v1.Signature signature = 2 [(validate.rules).message.required = true];
}

message IsCodeAccountResponse {
    Result result = 1;
    enum Result {
        // The account is a Code account.
        OK = 0;
        // The account is not a Code account.
        NOT_FOUND = 1;
        // The account exists, but at least one timelock account is unlocked.
        UNLOCKED_TIMELOCK_ACCOUNT = 2;
    }
}

message GetTokenAccountInfosRequest {
    // The owner account to fetch balances for, which can also be thought of as a
    // parent account for this RPC that links to one or more token accounts.
    common.v1.SolanaAccountId owner = 1 [(validate.rules).message.required = true];

    // The signature is of serialize(GetTokenAccountInfosRequest) without signature
    // fields set using the private key of the owner account. This provides
    // an authentication mechanism to the RPC.
    common.v1.Signature signature = 2 [(validate.rules).message.required = true];

    // A requesting owner account that is requesting the balance for owner. Additional
    // metadata that is considered private will be provided, if applicable. An example
    // use case includes a user owner account requesting account info for a gift card
    // owner account.
    common.v1.SolanaAccountId requesting_owner = 3;

    // The signature is of serialize(GetTokenAccountInfosRequest) without signature
    // fields set using the private key of the requesting_owner_signature account.
    // This provides an authentication mechanism to the RPC when requesting_owner is
    // present.
    //
    // This must be set when requesting_owner is present.
    common.v1.Signature requesting_owner_signature = 4;

    // Filter to apply to limit response sizes
    oneof Filter {
        common.v1.SolanaAccountId filter_by_token_address = 10;
        common.v1.AccountType     filter_by_account_type  = 11;
        common.v1.SolanaAccountId filter_by_mint_address  = 12;
    }
}

message GetTokenAccountInfosResponse {
    Result result = 1;
    enum Result {
        OK = 0;
        NOT_FOUND = 1;
    }

    map<string, TokenAccountInfo> token_account_infos = 2;

    // The next index clients should use for POOL account types
    uint64 next_pool_index = 3;
}

message TokenAccountInfo {
    // The token account's address
    common.v1.SolanaAccountId address = 1 [(validate.rules).message.required = true];

    // The owner of the token account, which can also be thought of as a parent
    // account that links to one or more token accounts. This is provided when
    // available.
    common.v1.SolanaAccountId owner = 2;

    // The token account's authority, which has access to moving funds for the
    // account. This can be the owner account under certain circumstances (eg.
    // ATA, primary account). This is provided when available.
    common.v1.SolanaAccountId authority = 3;

    // The type of token account, which infers its intended use.
    common.v1.AccountType account_type = 4 [(validate.rules).enum.not_in = 0];

    // The account's derivation index for applicable account types. When this field
    // doesn't apply, a zero value is provided.
    uint64 index = 5;

    // The source of truth for the balance calculation.
    BalanceSource balance_source = 6;
    enum BalanceSource {
        // The account's balance could not be determined. This may be returned when
        // the data source is unstable and a reliable balance cannot be determined.
        BALANCE_SOURCE_UNKNOWN = 0;
        // The account's balance was fetched directly from a finalized state on the
        // blockchain.
        BALANCE_SOURCE_BLOCKCHAIN = 1;
        // The account's balance was calculated using cached values in Code. Accuracy
        // is only guaranteed when management_state is LOCKED.
        BALANCE_SOURCE_CACHE = 2;
    }

    // The balance in quarks, as observed by Code. This may not reflect the value
    // on the blockchain and could be non-zero even if the account hasn't been created.
    // Use balance_source to determine how this value was calculated.
    uint64 balance = 7;

    // The state of the account as it pertains to Code's ability to manage funds.
    ManagementState management_state = 8;
    enum ManagementState {
        // The state of the account is unknown. This may be returned when the
        // data source is unstable and a reliable state cannot be determined.
        MANAGEMENT_STATE_UNKNOWN = 0;
        // Code does not maintain a management state and won't move funds for this
        // account.
        MANAGEMENT_STATE_NONE = 1;
        // The account is in the process of transitioning to the LOCKED state.
        MANAGEMENT_STATE_LOCKING = 2;
        // The account's funds are locked and Code has co-signing authority.
        MANAGEMENT_STATE_LOCKED = 3;
        // The account is in the process of transitioning to the UNLOCKED state.
        MANAGEMENT_STATE_UNLOCKING = 4;
        // The account's funds are unlocked and Code no longer has co-signing
        // authority. The account must transition to the LOCKED state to have
        // management capabilities.
        MANAGEMENT_STATE_UNLOCKED = 5;
        // The account is in the process of transitioning to the CLOSED state.
        MANAGEMENT_STATE_CLOSING = 6;
        // The account has been closed and doesn't exist on the blockchain.
        // Subsequently, it also has a zero balance.
        MANAGEMENT_STATE_CLOSED = 7;
    }

    // The state of the account on the blockchain.
    BlockchainState blockchain_state = 9;
    enum BlockchainState {
        // The state of the account is unknown. This may be returned when the
        // data source is unstable and a reliable state cannot be determined.
        BLOCKCHAIN_STATE_UNKNOWN = 0;
        // The account does not exist on the blockchain.
        BLOCKCHAIN_STATE_DOES_NOT_EXIST = 1;
        // The account is created and exists on the blockchain.
        BLOCKCHAIN_STATE_EXISTS = 2;
    }

    // Deprecated must_rotate
    reserved 10;

    // Whether an account is claimed. This only applies to relevant account types
    // (eg. REMOTE_SEND_GIFT_CARD).
    ClaimState claim_state = 11;
    enum ClaimState {
        // The account doesn't have a concept of being claimed, or the state
        // could not be fetched by server.
        CLAIM_STATE_UNKNOWN = 0;
        // The account has not yet been claimed.
        CLAIM_STATE_NOT_CLAIMED = 1;
        // The account is claimed. Attempting to claim it will fail.
        CLAIM_STATE_CLAIMED = 2;
        // The account hasn't been claimed, but is expired. Funds will move
        // back to the issuer. Attempting to claim it will fail.
        CLAIM_STATE_EXPIRED = 3;
    }

    // For account types used as an intermediary for sending money between two
    // users (eg. REMOTE_SEND_GIFT_CARD), this represents the original exchange
    // data used to fund the account. Over time, this value will become stale:
    //  1. Exchange rates will fluctuate, so the total fiat amount will differ.
    //  2. External entities can deposit additional funds into the account, so
    //     the balance, in quarks, may be greater than the original quark value.
    //  3. The balance could have been received, so the total balance can show
    //     as zero.
    transaction.v2.ExchangeData original_exchange_data = 12;

    // The token account's mint
    common.v1.SolanaAccountId mint = 13;

    // Deprecated relationship
    reserved 16;

    // Time the account was created, if available. For Code accounts, this is
    // the time of intent submission. Otherwise, for external accounts, it is
    // the tiem created on the blockchain.
    google.protobuf.Timestamp created_at = 17;

    // For REMOTE_SEND_GIFT_CARD, if requesting_owner was provided, was
    // requesting_owner the issuer of the account.
    bool is_gift_card_issuer = 18;
}