Gini BlockGrid API

syntax = "proto3";

package Gini.Api;

// OVERVIEW:

// Each section within the "service UI" code block
below generally corresponds with a screen in the Gini Account Center GUI.
However, all the RPC calls in this API are designed to be executed by any type
of client that needs to interact with the Gini BlockGrid. For example: embedded
IoT devices, Web services, hardware wallets, banking system services (e.g., our
GCU systems), and many others.

// All Gini APIs are implemented using Twirp. Among other
things, this defines:

//

// * HTTP methods and headers

// * Error responses

// * Mapping of service and rpc names to endpoints

// * Encoding of requests and responses

//

// Specifically, the encoding can be:

//

// * Protobuf3

// * Protobuf3's JSON mapping

//

// The details are at https://developers.google.com/protocol-buffers/docs/proto3.

// The encoding is controlled by the client, using
`Content-Type` and `Accept` headers.

//

// Note that:

//

// * `string` fields may contain any valid Unicode character.

// * `bytes` fields may contain any byte, including nulls, and
will be

// base-64 encoded when JSON-mapped.

// * The int after each data type is simply the field order
within each of

// the spec's functions. These numbers don't need to be included
in any

// function calls.

//

// API naming conventions:

//

// * APIs are categorized as Information, Action or Delay

// * Information API names end with a noun

// - Read-only Information API names begin with Get

// - Write-only Information API names begin with Set/Unset

// - Read-Write Information API names begin with
Read/Write/Delete

// * Action API names begin with an imperative verb

// * Delay APIs begin with Poll

//

// Data representation:

//

// * Public keys are expressed as strings in Gini's custom
base-32 notation

// (eg
"gini_1czim7y8ddzpihfbzwctqbrokoek83c84s9jt5zd56as1cdanxm4jxxwnbap")

// * Block hashes are expressed as 64-character,
case-insensitive hex strings

// (eg
"a286fd300598bf0c8ccc1196943b9ceb94f268cc89f2010b7f7ee4055cc6ab8c")

// * Blob keys can be any valid Unicode string.

// There is an implementation-defined upper limit on their
size.

// * Blob contents are arbitrary binary values.

// There is an implementation-defined upper limit on their
size.

// * Amounts of gini are expressed as base-10 decimal strings
with 1.0 == 1 gini

// (eg "123.4567890123456789"). To be valid, values
must be within the range

// allowed by the currency, and have no more decimal places
than the precision

// of the currency. Integral values may omit the decimal
point.

//

// States:

//

// * A node may be uninitialized or initialized.

// * Once initialized, a node may also be locked.

// * An uninitialized node is always in the unlocked state and
cannot be locked.

// * All rpc's except Lock/Unlock return an error if the node
is locked.

// * A node will automatically lock itself after a period of no
API activity.

// * The length of the period is configurable but defaults to 5
minutes.

 

// The Wallet service allows a Gini wallet UI to interact with a
Gini node.

service Wallet {

 

// SETUP:

 

// See the SETTINGS APIs for configuring GCU details and
enabling logging.

 

// Get the list of languages for which backup phrases may be
generated.

rpc GetBackupPhraseLanguages(EmptyReq) returns (GetBackupPhraseLanguagesResp);

// Generate a new backup phrase using cryptographically secure
entropy.

rpc GenerateBackupPhrase(GenerateBackupPhraseReq) returns (GenerateBackupPhraseResp);

 

// Initialize the node with an existing user's identity (secret
key and password).

// Returns an error if the node has already been initialized.

rpc SetUser(SetUserReq) returns (SuccessResp);

// Remove all user-specific data from the node and return it to
the uninitialized state.

rpc UnsetUser(UnsetUserReq) returns (SuccessResp);

 

// INTERNAL:

 

// Lock the node .

rpc Lock(EmptyReq) returns (SuccessResp);

// Unlock the node with the UI password.

rpc Unlock(UnlockReq) returns (SuccessResp);

 

// Get information about the user's account.

rpc GetAccountInfo(EmptyReq) returns (AccountInfoResp);

 

// ACCOUNTS:

 

// Obtain the user's Gini account balance.

rpc GetBalance(EmptyReq) returns (GetBalanceResp);

// Send Gini to another account.

rpc Send(SendReq) returns (SendResp);

 

// Read the binary blob associated with a given string.

// Note: The stored blob is encrypted with the user's Gini key.

rpc ReadBlob(ReadBlobReq) returns (ReadBlobResp);

// Write the binary blob associated with a given string.

// Note: The stored blob is encrypted with the user's Gini key.

rpc WriteBlob(WriteBlobReq) returns (SuccessResp);

// Delete the binary blob associated with a given string.

rpc DeleteBlob(DeleteBlobReq) returns (SuccessResp);

 

// HISTORY:

 

// Read the user's transaction history.

rpc GetHistory(GetHistoryReq) returns (GetHistoryResp);

// Read the details of a specified transaction.

rpc GetTransaction(GetTransactionReq) returns (GetTransactionResp);

 

// Wait for a transaction's state to differ from the specified
state.

// Returns an error if the specified state is already final
(confirmed/failed).

// Includes a specified timeout.

rpc PollTransaction(PollTransactionReq) returns (PollTransactionResp);

// Wait for a new transaction to be received.

// Returns immediately if the requested hash is not the latest.

// Includes a specified timeout.

rpc PollReceive(PollReceiveReq) returns (PollReceiveResp);

 

// SETTINGS:

 

// Change the UI password.

rpc SetPassword(SetPasswordReq) returns (SuccessResp);

// Read the user's configurable options.

rpc ReadOptions(EmptyReq) returns (ReadOptionsResp);

// Write the user's configurable options.

rpc WriteOptions(WriteOptionsReq) returns (SuccessResp);

}

 

// An EmptyReq contains no data.

message EmptyReq {

}

 

// A SuccessResp indicates the success of an operation.

message SuccessResp {

// The result.

bool success = 1; // Always true.

}

 

// A GetBackupPhraseLanguagesResp contains the list of languages
for which

// backup phrases may be generated.

message GetBackupPhraseLanguagesResp {

repeated string languages = 1;

}

 

// A GenerateBackupPhraseReq contains a request to generate a
new backup phrase.

message GenerateBackupPhraseReq {

// The language to be used for the backup phrase.

// If the language isn't supported, an error will be returned.

string language = 1;

}

 

// A GenerateBackupPhraseResp contains a new backup phrase.

message GenerateBackupPhraseResp {

// A new backup phrase. It isn't retained by the node. Instead,
it is displayed

// to the user who must then write it down and keep it safe.

// It will typically be combined with a password in a SetUser
request to

// create a secret key.

string phrase = 1;

}

 

// A SetUserReq contains a request to initialize the node with a
user's identity.

message SetUserReq {

// The backup phrase that represents the user's account.

// It MUST have been written down and kept safe.

string backup_phrase = 1;

// The password that is combined with the backup phrase to
produce the secret key.

// It MUST be provided whenever the backup phrase is used again
in the future.

// The password may be empty, in which case the phrase is
unprotected and may be

// used as-is to obtain the user's secret key.

string backup_password = 2;

// The UI password used for protecting access to the node.

// It is required whenever the node starts up and when the node
is unlocked after being locked.

// It is also used for encrypting the user's data on disk.

// It may be the same as the password used with the backup
phrase or it may be different.

// However, it may not be empty.

string ui_password = 3;

}

 

// An UnsetUserReq contains a request to remove all
user-specific data from the node.

message UnsetUserReq {

// The UI password used for protecting access to the node.

string password = 1;

}

 

// A UnlockReq contains a request to put the node into an
unlocked state.

message UnlockReq {

// The UI password used for protecting access to the node.

string password = 1;

}

 

// An AccountInfoResp contains information about the user's
account.

// Returns an error if the node is locked.

message AccountInfoResp {

// The user's public key in base-32 notation.

string account = 1;

}

 

// A GetBalanceResp contains the amount of Gini in an account.

message GetBalanceResp {

// The amount of Gini in the account, as a base-10 decimal
string.

string amount = 1;

// The hash of the most recent block in the account.

string hash = 2;

}

 

// A SendReq contains a request to send funds to another
account.

message SendReq {

// The account that funds are being sent to.

string destination = 1;

// The amount of Gini that is being sent, as a base-10 decimal
string.

string amount = 2;

// The memo field of the transaction.

string memo = 4;

}

 

// A SendResp contains the details of a newly-created
transaction.

message SendResp {

// The hash of the transaction's block.

string hash = 1;

}

 

// A ReadBlobReq contains a request to read the content of a
blob.

message ReadBlobReq {

// The id of the blob to be read. The id can be any non-empty
Unicode string.

string blob_id = 1;

}

// A ReadBlobResp contains the content of a blob.

message ReadBlobResp {

// The content of the blob. It can be any binary value, and may
contain null bytes.

bytes content = 1;

}

 

// A WriteBlobReq contains a request to write the content of a
blob.

message WriteBlobReq {

// The id of the blob to be written. The id can be any non-empty
Unicode string.

string blob_id = 1;

// The content of the blob. It can be any binary value, and may
contain null bytes.

bytes content = 2;

}

 

// A DeleteBlobReq contains a request to delete a blob.

message DeleteBlobReq {

// The id of the blob to be deleted. The id can be any non-empty
Unicode string.

string blob_id = 1;

}

 

// A GetHistoryReq contains a request for a list of transactions
as block hashes.

message GetHistoryReq {

// The hash of the most recent block whose history is to be
fetched.

// Note: the most recent transaction in the account can be
obtained using GetBalance.

string starting_with = 1;

// The number of history entries to be fetched.

uint32 count = 2;

}

// A GetHistoryResp contains a list of transactions as block
hashes.

message GetHistoryResp {

// A list of block hashes.

repeated string hashes = 1;

}

 

// A TransactionDirection specifies whether a transaction was
sent or received.

enum TransactionDirection {

SEND = 0;

RECEIVE = 1;

}

 

// A TransactionStatus represents the state of the send block
that was created by a transaction.

enum TransactionStatus {

PENDING = 0;

CONFIRMED = 1;

FAILED = 2;

}

 

// A GetTransactionReq contains a request for the details of a
transaction.

message GetTransactionReq {

// The hash of the block containing the transaction.

string hash = 1;

}

// A GetTransactionResp contains information about a
transaction.

message GetTransactionResp {

// Whether the transaction was sent or received.

TransactionDirection direction = 1;

// The other account involved in the transaction.

string account = 2;

// The amount of the transaction.

string amount = 3;

// The memo field of the transaction (empty for receive
transactions).

string memo = 4;

// The status of the transaction.

TransactionStatus status = 5;

}

 

// A PollTransactionReq contains a request to wait until a
transaction changes state.

message PollTransactionReq {

// The hash of the transaction's block.

string hash = 1;

// The current status of the transaction.

TransactionStatus status = 2;

// The maximum length of time in seconds to wait for a change in
status.

// There is an implementation-defined upper limit on the value;
values greater than this

// will be clipped to the maximum. Non-positive values will be
treated as an error.

float timeout = 3;

}

// A PollTransactionResp contains the current state of a
transaction.

message PollTransactionResp {

// The status of the transaction.

TransactionStatus status = 1;

}

 

// A PollReceiveReq contains a request to wait until a new
transaction is received.

message PollReceiveReq {

// The hash of the most recent transaction's block (eg obtained
from GetAccountInfo).

string hash = 1;

// The maximum length of time in seconds to wait for a
transaction.

// There is an implementation-defined upper limit on the value;
values greater than this

// will be clipped to the maximum. Non-positive values will be
treated as an error.

float timeout = 2;

}

// A PollTransactionResp contains the current state of a
transaction.

message PollReceiveResp {

// The hash of the new transaction's block.

// It will be the same as the requested hash if the request
times out.

string hash = 1;

}

 

// A SetPasswordReq contains a request to change the user's UI
password.

// Note: this does not change the password used with the backup
phrase.

message SetPasswordReq {

// The new password.

string password = 1;

}

 

// An UserOptions contains the user's configurable options.

message UserOptions {

// The GCU details.

string gcu_details = 1;

// Whether to enable logging.

bool logging_enabled = 2;

// Whether to require the password to send.

bool send_requires_password = 3;

// Whether to operate as a full node.

bool full_node = 4;

// Whether to enable Dynamic Guardian eligibility.

bool dynamic_guardian = 5;

// Whether to group accounts of the same currency.

bool group_accounts = 6;

// The lock timeout in minutes.

float lock_timeout = 7;

}

 

// A ReadOptionsResp contains the user's option settings.

message ReadOptionsResp {

// The options.

UserOptions options = 1;

}

 

// A WriteOptionsReq contains a request to write the user's
option settings.

message WriteOptionsReq {

// The options.

UserOptions options = 1;

}