syntax="proto3";
import "google/protobuf/empty.proto";
import "securityMessages.proto";
import "oracleMessages.proto";
import "treasuryMessages.proto";
import "bbMessages.proto";
import "logisticsMessages.proto";
import "validate/validate.proto";
package onliCloudApi;
option go_package="github.com/onlicorp/onli-cloud-api/onliCloudApi";

// The OnliCloudApi service definition.
service OnliCloudApi {
    /****** Transfer-agent Calls *******/
    // ChangeOwner changes ownership of genomes. Pre-requisite: AskToMove  
    // Example Input:  
    // {  
    //     "from": "example sender user_id",  
    //     "to": "example recipient user_id",  
    //     "ask_to_move_id": "example ask_to_move_id",  
    //     "app_symbol": "ABCDE",  
    //     "amount": 1,   
    //     "which_device": "desktop"  
    // }  
    // Example Output:  
    // {  
    //     "ask_to_move_id": "example ask_to_move_id",  
    //     "evolve_id": "5487fa89-b0ca-47ec-a582-79a5ee61d808",  
    //     "received_at": "1742211777",  
    //     "owner_evolved_at": "1742211777",  
    //     "delivered_at": "1742211778"  
    // }  
    // Possible errors:  
    // 1.  Code: InvalidArgument, Err: Validation errors, Reason: Invalid input data
    // 2.  Code: Unavailable, Err: unable to initialize SecurityTray client, Reason: OCT not able to connect to SecurityTray
    // 3.  Code: Internal, Err: unable to GetAskToMoveRecord from SecurityTray, Reason: Internal error in securityTray GetAskToMoveRecord flow
    // 4.  Code: Unauthenticated, Err: askToMoveRecord.Status is not open, Reason: AskToMoveRecord is not open
    // 5.  Code: InvalidArgument, Err: askToMoveRecord.PkgTag is empty, Reason: Invalid input pkg_tag
    // 6.  Code: InvalidArgument, Err: askToMoveRecord.Amount is not equal to input.Amount, Reason: Invalid input amount
    // 7.  Code: Unavailable, Err: unable to initialize transfer client, Reason: OCT not able to connect to transfer-agent
    // 8.  Code: Internal, Err: unable to EvolveOwner, Reason: Internal error in transfer-agent EvolveOwner flow
    // 9.  8a.Code: InvalidArgument, Err: Validation errors, Reason: Invalid input data
    // 10. 8b.Code: Unavailable, Err: unable to get move stream, Reason: transfer-agent unable to get move stream
    // 11. 8c.Code: Internal, Err: unable to unable to SendUnshipInput, Reason: Internal error in logistics SendUnshipInput flow
    // 12. 8d.Code: Internal, Err: unable to GetGenomes from pkg, Reason: Internal error in transfer-agent GetGenomes from pkg flow
    // 13. 8e.Code: Unauthenticated, Err: invalid pkg, Reason: the package has some validation errors
    // 14. 8f.Code: Internal, Err: unable to SendUnshipInput, Reason: Internal error in logistics SendUnshipInput flow
    // 15. 8g.Code: Unavailable, Err: unable to get oracle client, Reason: TransferAgent not able to connect to oracle
    // 16. 8h.Code: Internal, Err: unable to UpdateOwners, Reason: Internal error in oracle UpdateOwners flow
    // 17. 8i.Code: Internal, Err: unable to encrypt genomes, Reason: Internal error in transfer-agent encrypt genomes flow
    // 18. 8j.Code: Internal, Err: unable to Put pkg in transfer-agent vault, Reason: Internal error in transfer-agent vault
    // 19. 8k.Code: Internal, Err: unable to ConfirmCopied, Reason: TransferAgent unable to confirm copy with the owner
    // 20. 8l.Code: Internal, Err: unable to ship, Reason: unable to ship to the new locker
    // 21. 8m.Code: Internal, Err: unable to delete pkg from transfer-agent vault, Reason: Internal error in transfer-agent vault
    // 22. Code: Internal, Err: unable to CloseAskToMove, Reason: Internal error in securityTray CloseAskToMove flow
    rpc ChangeOwner(ChangeOwnerInput) returns (ChangeOwnerResponse) {}
    // Reship reships failed packages in transfer-agent  
    // Apps involved: logistics, transfer-agent  
    // Example Input:  
    // {  
    //     "pkg_tag": "12e4397f-ccfd-465c-a844-de90df7e9421"  
    // }  
    // Example Output:  
    // {  
    //     "change_id": "49516a91-cced-4561-bfba-51894ac4b303",  
    //     "delivered_at": "1764227434"  
    // }  
    // Possible errors:  
    // 1. Code: Internal, Err: unable to initialize transfer client, Reason: OCT not able to connect to transfer-agent
    // 2a.Code: Internal, Err: unable to ship, Reason: unable to ship to the new locker
    // 2b.Code: Internal, Err: unable to delete pkg from transfer-agent vault, Reason: Internal error in transfer-agent vault
    rpc Reship(ReshipInput) returns (ReshipResponse) {}
    // ListFailedPackages lists failed packages in transfer-agent  
    // Apps involved: logistics, transfer-agent  
    // Example Input:  
    // {  
    //     "page_limit": "2",  
    //     "page_number": "1"  
    // }  
    // Example Output:  
    // {  
    //     "failed_pkgs": [  
    //         {  
    //             "pkg_tag": "0df789cb-67fa-46b4-a9c0-6dbc87416419",  
    //             "current_owner": "usr-00514712-42df-564a-adb6-74614d4c9415",  
    //             "source": "lkr-076543df-547c-443b-b019-ad3c5b7ff756",  
    //             "destination": "vlt-107c5726-ad2a-46a0-b02a-5ed0c3763e45",  
    //             "amount": "1",  
    //             "app_symbol": "ENGMA"  
    //         },  
    //         {  
    //             "pkg_tag": "12e4397f-ccfd-465c-a844-de90df7e9421",  
    //             "current_owner": "usr-f920cc54-62b7-5764-8e07-7035e36d2828",  
    //             "source": "lkr-076543df-547c-443b-b019-ad3c5b7ff756",  
    //             "destination": "vlt-107c5726-ad2a-46a0-b02a-5ed0c3763e45",  
    //             "amount": "1",  
    //             "app_symbol": "ENGMA"  
    //         }  
    //     ]  
    // }  
    // Possible errors:  
    // 1. Code: Internal, Err: unable to initialize transfer client, Reason: OCT not able to connect to transfer-agent
    // 2a.Code: Internal, Err: unable to list failed packages, json.Unmarshal error, Reason: Internal error in transfer-agent
    // 2b.Code: Internal, Err: unable to list failed packages, IterateDB error, Reason: Internal error in transfer-agent
    rpc ListFailedPkgs(ListFailedPkgsInput) returns (FailedPkgs) {}

    /****** Treasury Calls *******/
    // Issue genomes from the treasury to an owner  
    // You can issue using either amount as input or onli_ids  
    // When onli_ids are provided, amount is ignored  
    // Example Input:  
    // {  
    //     "to": "example_user_id",  
    //     "app_symbol": "ABCDE",  
    //     "amount": "3000",  
    //     "which_device": "desktop",  
    //     "onli_ids": ["example_onli_id1", "example_onli_id2"]  
    // }  
    // Example Output:  
    // {  
    //     "issue_id": "d8042a84-5663-4cb2-94f7-aa61b581f320",  
    //     "issued_at": "1741701330",  
    //     "owner_changed_at": "1741701331",  
    //     "delivered_at": "1741701331",  
    //     "pkg_tag": "f608bcd5-4acb-49db-b288-54ea66800af0"  
    // }  
    // Possible errors:  
    // 1.  Code: InvalidArgument, Err: Validation errors, Reason: Invalid input data
    // 2.  Code: Unavailable, Err: unable to initialize treasury client, Reason: OCT not able to connect to treasury
    // 3.  Code: Unavailable, Err: unable to initialize ApplianceTray client, Reason: OCT not able to connect to ApplianceTray
    // 4.  Code: Internal, Err: treasury issue failed, Reason: Internal error in treasury
    // 5.  4a.Code: Unavailable, Err: unable to connect to transfer-agent, Reason: Treasury not able to connect to transfer-agent
    // 6.  4b.Code: Internal, Err: unable to GetGenoType, Reason: Internal error in treasury GetGenoType flow
    // 7.  4c.Code: InvalidArgument, Err: incorrect app_symbol, Reason: The provided app_symbol doesn't match treasury app_symbol
    // 8.  4d.Code: Internal, Err: unable to GetGenomes, Reason: Internal error in treasury GetGenomes flow
    // 9.  4e.Code: Internal, Err: unable to CallShip, Reason: Internal error in treasury CallShip flow
    // 10. 4f.Code: Internal, Err: unable to EvolveOwner, Reason: Internal error in transfer-agent EvolveOwner flow
    // 11. 4g.Code: Internal, Err: unable to AddBreadcrumb, Reason: Internal error in treasury AddBreadcrumb flow
    // 12. Code: Internal, Err: applianceTray incrementIssuedCount failed, Reason: ApplianceTray not able to increment issued count
    rpc Issue(IssueInput) returns (IssueResponse) {}
    // ManageReserveStream moves genomes from reserve (not issuable) to inventory (issuable).  
    // It is a bi-directional stream.  
    // The client sends the face valorum of each genome to be moved.  
    // The client can also send the basepairs of each genome to be moved.  
    // The server returns the onli_id and the face valorum of the moved genome.  
    // Example Input:  
    // {  
    //     "face": "one",  
    //     "basepairs": [{"base": "base1", "pair": "pair1"}, {"base": "base2", "pair": "pair2"}],  
    // }  
    // Example Output:  
    // {  
    //     "onli_id": "example onli_id",  
    //     "face": "one"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize treasury client, Reason: OCT not able to connect to treasury
    // 2. Code: Internal, Err: unable to ManageReserve, Reason: Internal error in treasury
    // 3. 2a.Code: Unavailable, Err: unable to connect to oracle, Reason: Treasury not able to connect to oracle
    // 4. 2b.Code: Unavailable, Err: unable to call UpdateStateStream, Reason: Treasury not able to call oracle method UpdateStateStream
    rpc ManageReserveStream(stream treasuryApi.ManageReserveStreamInput) returns (stream treasuryApi.ManageReserveStreamResponse) {}
    // Blacklisting this genome will permanently mark said Genome as invalid in the Oracle.  
    // This action cannot be undone. Blacklisting will prevent any AskToMove and ChangeOwner request from succeeding.  
    // However, the owner will maintain ownership of said Genome and can freely move the Genome between their vaults.  
    // Example Input:  
    // {  
    //     "which_onli": "example onli_id",  
    //     "current_owner_id": "example user_id",  
    //     "blacklist_reason": "example_reason",  
    //     "blacklisted_by": "example_appliance_admin user_id"  
    // }  
    // Example Output:  
    // {  
    //     "status": 0  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize treasury client, Reason: OCT not able to connect to treasury
    // 2. Code: Internal, Err: unable to Blacklist, Reason: Internal error in treasury
    // 3. 2a.Code: Unavailable, Err: unable to connect to oracle, Reason: Treasury not able to connect to oracle
    // 4. 2b.Code: NotFound, Err: unable to GetBreadcrumbRecord, Reason: Treasury not able to find BreadcrumbRecord
    // 5. 2c.Code: Internal, Err: unable to UpdateBreadcrumbRecord, Reason: Treasury not able to update BreadcrumbRecord
    // 6. 2d.Code: Internal, Err: unable to Blacklist, Reason: Internal error in treasury Blacklist flow
    // 7. 2e.Code: Internal, Err: unable to Blacklist in oracle, Reason: Internal error in Oracle Blacklist flow
    rpc Blacklist(treasuryApi.BlacklistInput) returns (treasuryApi.BlacklistResponse) {}
    // List returns a paginated list of genomes in a specific treasury vault type  
    // Vault types: reserve (not issuable), inventory (issuable), issued (genome history), blacklisted  
    // Scopes: Manifest, Count, CurrentOwner, Face, Genotype, NT, All
    // Example Input:  
    // {  
    //     "page_number": "1",  
    //     "page_limit": "10",  
    //     "scope": "All",  
    //     "vault_type": "inventory"  
    // }  
    // Example Output:  
    // {  
    //     "face_stats": [  
    //         {  
    //             "face": "one",  
    //             "count": "2"  
    //         }  
    //     ],  
    //     "ListRecords": [  
    //         {  
    //             "onli_you_id": "onli-you-id-1",  
    //             "current_owner": "treasury",  
    //             "app_symbol": "ABCDE",  
    //             "genus": "denomination",  
    //             "face": "one",  
    //             "content_helix": ["vault1", "vault2"],  
    //         },  
    //         {  
    //             "onli_you_id": "onli-you-id-1",  
    //             "current_owner": "treasury",  
    //             "app_symbol": "ABCDE",  
    //             "genus": "denomination",  
    //             "face": "one"  
    //             "content_helix": ["vault1", "vault2"],      
    //         }  
    //     ],  
    //     "count": "2",  
    //     "net_amount": "2"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize treasury client, Reason: OCT not able to connect to treasury
    // 2. Code: Internal, Err: unable to List, Reason: Internal error in treasury
    rpc List(treasuryApi.ListInput) returns (treasuryApi.ListResponse) {}
    // FetchGenome returns the genome data for a specific onli_id from treasury  
    // Vault types: inventory (issuable)  
    // Example Input:  
    // {  
    //     "onli_id": "onl-a67c5d0a-84e4-4364-8109-b7b2a25eb3a1"  
    // }  
    // Example Output:  
    // {  
    //     "identity_helix": [  
    //         "onl-00076728-8d42-5c05-9894-0d8ee6b0b80a",  
    //         "Us Patent App. No. 16/636,195",  
    //         "onli_v3.0.0"  
    //     ],  
    //     "owner_helix": [  
    //         "usr-35931626-d438-56fb-8456-2133551bc2b9"  
    //     ],  
    //     ...  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize treasury client, Reason: OCT not able to connect to treasury
    // 2. Code: Internal, Err: unable to FetchGenome, Reason: Internal error in treasury
    rpc FetchGenome(treasuryApi.FetchGenomeInput) returns (treasuryApi.FetchGenomeResponse) {}


    /****** SecurityTray Calls *******/
    // AskToView is initiated by a master and a notification is sent to the owner for permission to view oracle records  
    // Example Input:  
    // {  
    //     "app_symbol": "ABCDE",  
    //     "auth_by": "example owner user_id",  
    //     "how_long": "1",  
    //     "when": "1736854564",  
    //     "which_onli": ["example onli_id"],  
    //     "who_can_view": "example viewer user_id"  
    // }  
    // Example Output:  
    // {  
    //     "which_onli": ["example onli_id"],  
    //     "ask_to_view_id": "4ed51902-aa96-455e-a156-7ae1572e7e28",  
    //     "auth_by": "example owner user_id",  
    //     "who_can_view": "example viewer user_id",  
    //     "when": "1736854564",  
    //     "how_long": "1",  
    //     "app_symbol": "ABCDE",  
    //     "is_owner": true,  
    //     "status": "ASKED"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize SecurityTray client, Reason: OCT not able to connect to SecurityTray
    // 2. Code: Internal, Err: unable to AskToView, Reason: Internal error in SecurityTray
    // 3. 2a.Code: InvalidArgument, Err: failed to retrieve metadata from context, Reason: OCT sent invalid metadata to SecurityTray
    // 4. 2b.Code: Internal, Err: failed to add auth_to_view_policy to database, Reason: SecurityTray not able to add auth_to_view_policy
    // 5. 2c.Code: Internal, Err: failed to notify the viewer, Reason: SecurityTray not able to notify the viewer using queue
    rpc AskToView(securityApi.AskToViewReq) returns (securityApi.AuthToViewPolicy) {}
    // UpdateSettlementTime controls the default settlement time expiry for genome packages in lockers  
    // Example Input:  
    // {  
    //     "app_symbol": "ABCDE",  
    //     "settlement_seconds": "15768000" // 2 years  
    // }  
    // Example Output:  
    // {  
    //     "auth_log_id": "example auth-log-id"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize SecurityTray client, Reason: OCT not able to connect to SecurityTray
    // 2. Code: Internal, Err: unable to UpdateSettlementTime, Reason: Internal error in SecurityTray
    rpc UpdateSettlementTime(securityApi.SettlementTimeReq) returns (securityApi.AuthLogIdResp) {}
    // AskToMove workflow is a bi-directional stream used to Ask an owner to move their genomes to their locker   
    // which can then be used with ChangeOwner to transfer to another owners locker.  
    // This request is initiated by a master and a notification is sent to the owner.  
    // The owner can either accept or deny the request.   
    // Example Input:  
    // {  
    //     "add_settle_time": "0",  
    //     "amount": "1",  
    //     "app_symbol": "ABCDE",  
    //     "note": {  
    //         "behavior": "move",  
    //         "body": "Accept ask to move request from ABCDE"  
    //     },  
    //     "to": "example user_id"  
    // }  
    // Example Output:  
    // {  
    //     "ask_to_move_id": "example ask-to-move-id",  
    //     "pkg_tag": "example pkg_tag",  
    //     "to": "example user_id",  
    //     "note": {  
    //         "behavior": "move",  
    //         "body": "Accept ask to move request from ABCDE"  
    //     },  
    //     "amount": "1",  
    //     "app_symbol": "ABCDE",  
    //     "asset_balance": "2008",  
    //     "notified_at": "1741866953",  
    //     "status": "OPEN",  
    //     "expires_at": "1757634953",  
    //     "behavior_status": true,  
    //     "authorization_status": true,  
    //     "auth_log_id": "example auth-log-id"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize SecurityTray client, Reason: OCT not able to connect to SecurityTray
    // 2. Code: Unavailable, Err: unable to get AskToMoveStream, Reason: OCT not able to start AskToMoveStream
    // 3. Code: Internal, Err: error in AskToMoveStream, Reason: Internal error in SecurityTray
    // 4. 3a.Code: Internal, Err: unable to add/update ask_to_move_record, Reason: SecurityTray not able to add/update ask_to_move_record
    // 5. 3b.Code: Internal, Err: failed to notify the app, Reason: SecurityTray not able to notify the app
    // 6. 3c.Code: Internal, Err: failed to notify the owner, Reason: SecurityTray not able to notify the owner
    rpc AskToMoveStream(stream securityApi.AskToMoveReq) returns (stream securityApi.AskToMoveRecord) {}
    // Get AskToMoveRecord using ask_to_move_id  
    // Example Input:  
    // {  
    //     "ask_to_move_id": "example ask_to_move_id"  
    // }  
    // Example Output:  
    // {  
    //     "ask_to_move_id": "example ask-to-move-id",  
    //     "pkg_tag": "example pkg_tag",  
    //     "to": "example usr-id",  
    //     "note": {  
    //         "behavior": "move",  
    //         "body": "Accept ask to move request from ABCDE"  
    //     },  
    //     "amount": "1",  
    //     "app_symbol": "ABCDE",  
    //     "asset_balance": "2008",  
    //     "notified_at": "1741866953",  
    //     "status": "OPEN",  
    //     "expires_at": "1757634953",  
    //     "behavior_status": true,  
    //     "authorization_status": true,  
    //     "auth_log_id": "example auth-log-id"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize SecurityTray client, Reason: OCT not able to connect to SecurityTray
    // 2. Code: Internal, Err: unable to GetAskToMoveRecord, Reason: Internal error in SecurityTray
    // 3. 2a.Code: NotFound, Err: unable to find ask_to_move_record for ask_to_move_id, Reason: AskToMoveRecord not found in database
    // 4. 2b.Code: DeadlineExceeded, Err: the ask_to_move_record with ask_to_move_id has expired, Reason: the ask_to_move_record has expired
    rpc GetAskToMoveRecord(securityApi.AskToMoveIdReq) returns (securityApi.AskToMoveRecord) {}
    // ReturnAskToMove is used to cancel the ask_to_move transaction   
    // and return the genome package from owners locker back to owners vault  
    // Example Input:  
    // {  
    //     "ask_to_move_id": "example ask_to_move_id"  
    // }  
    // Example Output:  
    // {  
    //     "ask_to_move_id": "example ask_to_move_id",  
    //     "pkg_tag": "example pkg_tag",  
    //     "to": "example usr-id",  
    //     "status": "RETURNED",  
    //     "amount": "1",  
    //     "app_symbol": "ABCDE",  
    //     "auth_log_id": "example auth-log-id"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize SecurityTray client, Reason: OCT not able to connect to SecurityTray
    // 2. Code: Unavailable, Err: unable to initialize Logistics client, Reason: OCT not able to connect to Logistics
    // 3. Code: Internal, Err: unable to ReturnAskToMove, Reason: Internal error in SecurityTray
    // 4. 3a.Code: NotFound, Err: unable to delete ask_to_move_record, Reason: AskToMoveRecord not found in database
    // 5. Code: Internal, Err: unable to ReturnPackage in logistics, Reason: Internal error in Logistics
    rpc ReturnAskToMove(securityApi.AskToMoveIdReq) returns (securityApi.ReturnAskToMoveResp) {}
    // AskToAdd is used to add settlement time to a specific AskToMoveRecord  
    // Example Input:  
    // {  
    //     "add_settle_time": "48",  
    //     "app_symbol": "ABCDE",  
    //     "ask_to_move_id": "example ask_to_move_id"  
    // }  
    // Example Output:  
    // {  
    //     "ask_to_move_id": "example ask_to_move_id",  
    //     "to": "example usr-id",  
    //     "amount": "3000",  
    //     "app_symbol": "ABCDE",  
    //     "status": "ASKED",  
    //     "expires_at": "1757814998",  
    //     "auth_log_id": "example auth-log-id"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize SecurityTray client, Reason: OCT not able to connect to SecurityTray
    // 2. Code: Internal, Err: unable to AskToAdd, Reason: Internal error in SecurityTray
    // 3. 2a.Code: NotFound, Err: unable to find ask_to_move_record for ask_to_move_id, Reason: AskToMoveRecord not found in database
    // 4. 2b.Code: InvalidArgument, Err: input.app_symbol doesn't match the record.app_symbol, Reason: Invalid input data
    // 5. 2c.Code: Internal, Err: unable to add/update ask_to_move_record, Reason: Internal error in SecurityTray
    // 6. 2d.Code: Internal, Err: unable to notify the app, Reason: SecurityTray unable to notify the app
    // 7. 2e.Code: Internal, Err: unable to notify the owner, Reason: SecurityTray unable to notify the owner
    rpc AskToAdd(securityApi.AskToAddReq) returns (securityApi.AskToMoveRecord) {}

    /****** Oracle Calls *******/
    // RevealGenomes returns oracle helix records for a specified owner  
    // Example Input:  
    // {  
    //     "search_condition": "what_face", // the column to search, supports * as wildcard also, leave empty for no search  
    //     "search_keyword": "^one|kilo$", // regex supported search query  
    //     "limit": "1000", // limit of records  
    //     "offset": "0", // offset of records  
    //     "sort_by": "what_face", // sort using this column, leave empty for no sorting  
    //     "sort_order": ASC, // ASC for ascending, DESC for descending    
    //     "who": "{{user_id}}" // user id of the owner  
    // }  
    // Example Output:  
    // {  
    //     "OracleHelices": [  
    //         {  
    //             "which_onli": "example onl-id",  
    //             "what_kind": "ABCDE",  
    //             "what_type": "denomination",  
    //             "what_face": "one",  
    //             "last_owner_id": "example last usr-id",  
    //             "last_owner_name": "treasury",  
    //             "current_owner_id": "example usr-id",  
    //             "current_owner_name": "example name",  
    //                 ...  
    //                 ...  
    //             "blacklisted": false,  
    //             "last_updated": "1738780042109969295",  
    //         }  
    //     ]  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize GenomeOracleUser client, Reason: OCT not able to connect to GenomeOracle
    // 2. Code: Internal, Err: unable to get RevealGenomes, Reason: Internal error in GenomeOracle
    // 3. 2a.Code: Internal, Err: unable to find onli_id in oracle database, Reason: Internal error in oracle database
    rpc RevealGenomes (gOracleApi.RevealGenomesInput) returns (gOracleApi.RevealGenomesResp) {}
    // TimeRevealGenomes returns oracle helix records for a specified owner  
    // during the specified time window that the owner approved  
    // Example Input:  
    // {  
    //     "app_symbol": "ABCDE",  
    //     "ask_to_view_id": "example ask_to_view_id",  
    //     "search_condition": "what_face", // the column to search, supports * as wildcard also, leave empty for no search  
    //     "search_keyword": "^one|kilo$", // regex supported search query  
    //     "limit": "1000", // limit of records  
    //     "offset": "0", // offset of records  
    //     "sort_by": "what_face", // sort using this column, leave empty for no sorting  
    //     "sort_order": ASC, // ASC for ascending, DESC for descending    
    //     "who": "{{user_id}}" // user id of the owner  
    // }  
    // Example Output:  
    // {  
    //     "OracleHelices": [  
    //         {  
    //             "which_onli": "example onl-id",  
    //             "what_kind": "ABCDE",  
    //             "what_type": "denomination",  
    //             "what_face": "one",  
    //             "last_owner_id": "example last usr-id",  
    //             "last_owner_name": "treasury",  
    //             "current_owner_id": "example usr-id",  
    //             "current_owner_name": "example name",  
    //                 ...  
    //                 ...  
    //             "blacklisted": false,  
    //             "last_updated": "1738780042109969295",  
    //         }  
    //     ]  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize GenomeOracleUser client, Reason: OCT not able to connect to GenomeOracle
    // 2. Code: Internal, Err: unable to get RevealGenomes, Reason: Internal error in GenomeOracle
    // 3. 2a.Code: Internal, Err: unable to find onli_id in oracle database, Reason: Internal error in oracle database    
    rpc TimeRevealGenomes (gOracleApi.TimeRevealGenomesInput) returns (gOracleApi.RevealGenomesResp) {}

    // RevealGenomeCount returns the count of oracle helix records for the specified owner_id  
    // Example Input:  
    // {  
    //     "who": "example viewer user_id",  
    // }  
    // Example Output:  
    // {  
    //     "net_oracle_helices": 10,  
    //     "net_amount": 100,  
    //     "face_map": {  
    //         "deca": 10  
    //     }  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize GenomeOracleUser client, Reason: OCT not able to connect to GenomeOracle
    // 2. Code: Internal, Err: unable to get RevealGenomeCount, Reason: Internal error in GenomeOracle
    rpc RevealGenomeCount (gOracleApi.RevealGenomeCountInput) returns (gOracleApi.GenomeCountResp) {}
    // TimedRevealGenomeCount returns the count of oracle helix records   
    // for the specified owner_id during the specified time window that the owner approved  
    // Example Input:  
    // {  
    //     "who": "example viewer user_id",  
    //     "ask_to_view_id": "example ask_to_view_id",  
    // }  
    // Example Output:  
    // {  
    //     "net_oracle_helices": 10,  
    //     "net_amount": 100,  
    //     "face_map": {  
    //         "deca": 10  
    //     }  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize GenomeOracleUser client, Reason: OCT not able to connect to GenomeOracle
    // 2. Code: Internal, Err: unable to get TimedRevealGenomeCount, Reason: Internal error in GenomeOracle
    rpc TimedRevealGenomeCount (gOracleApi.TimedRevealGenomeCountInput) returns (gOracleApi.GenomeCountResp) {}


    /****** Bill-Breaker Calls *******/
    // DrawerBalance returns bill-breaker face amounts in the vault drawer in denomination genus deployments  
    // Example Input:  
    // {}  
    // Example Output:  
    // {  
    //     "face_stats": [  
    //         {"face": "one","count": "7980"},  
    //         {"face": "deca","count": "8002"},  
    //     ],  
    //     "amount": "88000",  
    //     "count": "15982"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize bill-breaker client, Reason: OCT not able to connect to BillBreaker
    // 2. Code: Internal, Err: unable to get DrawerBalance, Reason: Internal error in BillBreaker
    rpc DrawerBalance(google.protobuf.Empty) returns (bbApi.Balance) {}
    // InitIssueDrawer is a denominational only method that issues genomes to the bill breaker vault,  
    // so owners can retrieve change when necessary during move operations.  
    // This method is used to initialize issue drawer workflow and only works on denominational cloud instances.  
    // This is a fire-and-forget method that returns a response immediately and  
    // the issue drawer progress can be monitored using DrawerBalance method.  
    // Example Input:  
    // {  
    // "face_stats": [  
    //     {  
    //          "face": "One",  
    //          "count": "8000"  
    //     }  
    // }  
    // Example Output:  
    // {  
    //     "status": "1"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize bill-breaker client, Reason: OCT not able to connect to BillBreaker  
    // 2. Code: Internal, Err: unable to connect to TreasuryClient server, Reason: BillBreaker unable to connect to TreasuryClient  
    // 3. Code: Internal, Err: unable to get List response, Reason: BillBreaker unable to list inventory in treasury  
    // 4. Code: Internal, Err: insufficient inventory , Reason: Treasury doesn't have enough genomes in inventory  
    rpc InitIssueDrawer(bbApi.InitIssueDrawerInput) returns (bbApi.InitIssueDrawerResponse) {}

    /****** Logistics Calls *******/
    // GetLogisticsInfo returns locker info, the method supports multiple input and output formats.  
    // Authentication: master-id should be the member of the app_symbol  
    // input: user-id,app_symbol, output: list of pkgtags, locker-id  
    // input: pkgtag(s), output:re packing slip data (except payload(genomes)), locker-id  
    // input: locker id,app_symbol, output: pkgtag(s)  
    // input: onli-id,app_symbol, output: re packing slip data (except payload(genomes)), locker-id  
    // Example Input:  
    // {  
    //     "app_symbol": "ABCDE",  
    //     "onli_id": "example onl-id"  
    // }  
    // Example Output:  
    // {  
    //     "pkg_tags": [  
    //         "97f0d350-3b00-4dd2-a7b0-f8fa76d271e4"  
    //     ],  
    //     "packing_slips": [  
    //         {  
    //             "pkg_tag": "97f0d350-3b00-4dd2-a7b0-f8fa76d271e4",  
    //             "version": "1.0.0",  
    //             "transport_proto": "grpc",  
    //             "owner": "example usr-id",  
    //             "packing_date": "1730568677",  
    //             "count": 3,  
    //             "amount": "3",  
    //             ...  
    //             ...  
    //             "app_symbol": "ABCDE",  
    //             "which_device": "desktop"  
    //         }  
    //     ],  
    //     "locker_id": "example lkr-id"  
    // }  
    // Possible errors:  
    // 1. Code: Unavailable, Err: unable to initialize logistics client, Reason: OCT not able to connect to Logistics
    // 2. Code: Internal, Err: unable to GetLogisticsInfo, Reason: Internal error in Logistics
    // 3. 2a.Code: InvalidArgument, Err: unable to GetLocker, Reason: Unable to find locker using provided input
    // 4. 2b.Code: Internal, Err: unable to IterateLockerDB, Reason: Internal error in logistics IterateLockerDB flow
    // 5. 2c.Code: InvalidArgument, Err: invalid package tag, Reason: Invalid input pkg_tag
    // 6. 2d.Code: NotFound, Err: pkg with pkgTag not found in locker, Reason: Unable to find pkg with the provided pkgTag
    rpc GetLogisticsInfo(logisticsApi.InfoInput) returns (logisticsApi.Info) {}

	/****** Onli-Cloud-Tray Calls *******/
	// Get PkgSlip returns the packing slip for a package in a locker
	// This method supports multiple input formats:
	// input: ask_to_move_id, output: packing slip for the ask_to_move_id
	// input: pkg_tag, output: packing slip for the pkg_tag
	// input: locker_id, output: packing slips for the locker_id
	// input: owner, output: packing slips for the owner
	// Note: All above inputs are optional, if none provided then it returns all packing slips
	// 		 You can control the pagination using limit and offset
	// Example Input:
	// {
	//     "ask_to_move_id": "example ask_to_move_id",
	//     "pkg_tag": "example pkg_tag",	
	//     "locker_id": "example locker_id",
	//     "owner": "example owner",
	//     "limit": 10,
	//     "offset": 0	
	// }
	// Example Output:
	// {
	//     "slips": [
	//         {
	//             "ask_to_move_id": "example ask_to_move_id",
	//             "pkg_tag": "example pkg_tag",
	//             "owner": "example owner",	
	//             "locker_id": "example locker_id",	
	//             "app_symbol": "ABCDE",	
	//             "amount": 3,	
	//             "count": 3,
	//             "genus": "denomination",
	//         }
	//     ],
	//     "slips_count": 1
	// }
	// Possible errors:
	// 1. Code: Unavailable, Err: unable to initialize logistics client, Reason: OCT not able to connect to Logistics
	// 2. Code: InvalidArgument, Err: user_id is required in metadata, Reason: User ID not provided in metadata
	// 3. Code: PermissionDenied, Err: not allowed to access other user's packages, Reason: Only master can access other user's packages
	rpc GetPkgSlip (GetPkgInput) returns (PkgSlips) {}
}

message ChangeOwnerInput {
    // user-id of the sender 
    string from = 1; 
    // user-id of the receiver
    string to = 2; 
    // ask_to_move_id 
    string ask_to_move_id = 3; 
    // app_symbol of genomes in the package
    string app_symbol = 4 [(validate.rules).string.pattern="[A-Z]{2,5}"];
    // amount to support partial transfers
    uint64 amount = 5;
    // which_device will be used to select which device to autoUnship on receivers end
    logisticsApi.device which_device = 6 [(validate.rules).enum = { in: [1, 2, 3]} ];
}

message ChangeOwnerResponse {
    // ask_to_move_id
    string ask_to_move_id = 1; 
    // id of event logged (transaction id)
    string evolve_id = 2; 
    // timestamp of when unshipped from locker
    int64 received_at = 3; 
    // timestamp of when helixes updated
    int64 owner_evolved_at = 4; 
    // timestamp of confirmed shipment to locker
    int64 delivered_at = 5; 
}

message ReshipInput {
    string pkg_tag = 1;
}

message ReshipResponse {
    // id of event logged (transaction id)
    string change_id = 1; 
    // timestamp of confirmed shipment to locker
    int64 delivered_at = 2; 
} 

message ListFailedPkgsInput {
    uint64 page_limit = 1;
    uint64 page_number = 2;
}

message FailedPkg {
    string pkg_tag = 1;
    string current_owner = 2;
    string source = 3;
    string destination = 4;
    uint64 amount = 5;
    string app_symbol = 6;
}

message FailedPkgs {
    repeated FailedPkg failed_pkgs = 1;
}


message IssueInput {
    // user-id of the receiver
    string to = 1;
    // net face amount of genomes
    // if onli_ids are specified, amount will be ignored
    uint64 amount = 2;
    // app_symbol of the appliance
    string app_symbol = 3 [(validate.rules).string.pattern="[A-Z]{2,5}"];
    // which_device will be used to select which device to autoUnship on receivers end
    logisticsApi.device which_device = 5 [(validate.rules).enum = { in: [1, 2, 3]} ];
    // onli_ids of the genomes to be issued
    repeated string onli_ids = 6;
    // optional face for series genus
    string face = 7;
}

message IssueResponse {
    // id of event logged (transaction id)
    string issue_id  = 1;
    // timestamp of when unshipped from locker
    int64 issued_at = 2;
    // timestamp of when helixes updated
    int64 owner_changed_at = 3;
    // timestamp of confirmed shipment to locker
    int64 delivered_at = 4;
    // package tag of the package
    string pkg_tag = 5;
}

message GetPkgInput {
	// optional
	string ask_to_move_id = 1;
	// optional
	string pkg_tag = 2;
	// optional
	uint32 limit = 3;
	// optional
	uint32 offset = 4;
	// optional
	string owner = 5;
}

message PkgSlip {
	string ask_to_move_id = 1; // optional, if empty, then the pkg is not a2m pkg
	string pkg_tag = 2;
	string owner = 3;
	string app_symbol = 4;
	uint64 amount = 5;
	int32 count = 6;
	string genus = 7;
	string status = 8; // status of ask_to_move record
	int64 expires_at = 9; // expiration time of ask_to_move record
	string locker_id = 10;
}
message PkgSlips {
	repeated PkgSlip slips = 1;
	int32 slips_count = 2;
}