This page documents the services as defined in our protobuf specifications.

attrf.Account#

NameDescriptionType
Addressstring
PayProviderIDint32
ReceiveProviderIDint32
ReceiveWalletInfostring
CreatedAtstring
PayProviderattrf.PaymentProvider
ReceiveProviderattrf.PaymentProvider
Signaturebytes

attrf.AccountInfo#

NameDescriptionType
Addressstring
PayProviderIDint32
ReceiveProviderIDint32
ReceiveWalletInfostring
CreatedAtstring
PayProviderattrf.PaymentProviderInfo
ReceiveProviderattrf.PaymentProviderInfo
Signaturebytes

attrf.Compensation#

NameDescriptionType
Beneficiarystring
Valuestring
Currencystring
AttrValuestring

attrf.DelegatedOp#

NameDescriptionType
Hashstring
Rootstring
Agreementstring
RootCreatedAtint64
SignedDelegatedOperationcore.SignedDelegatedOperation
SignedDelegatedOperationBlob

internal field containt proto marshal blob of DelegatedOperation, could be empty

bytes
Compensationattrf.Compensation
StatusID

Available : 1-Pending, 2-Published, 3-Publish_Failed, 4-Confirmed, 5-Confirmed_Failed, 6-Paying, 7-Paid, 8-Paid_Failed

uint32
CreatedBy

Address of creator of this delegated op

string
CreatedAt

Optional, this often autogenerated when saving to db

int64
Feestring

attrf.DelegatedOperationReceipt#

NameDescriptionType
DopHashstring
ReceiptIDstring

attrf.DelegatedOperationUpdateRequest#

NameDescriptionType
DopHashstring
UpdateAttrValuebool
AttrValuestring
UpdateStatusbool
Statusuint32
UpdateFeebool
Feestring

attrf.GetAccountInfosRequest#

NameDescriptionType
Addresses[]string

attrf.GetAccountInfosResponse#

NameDescriptionType
Accounts[]attrf.AccountInfo

attrf.GetAggregatedRootRequest#

NameDescriptionType
Agreements[]string
FromTime

Filter `DelegatedOperations.RootCreatedAt` window begin, end
The number of milliseconds elapsed since January 1, 1970 UTC
Example: 1585967899000

int64
ToTimeint64
ModifiedFrom

Filter `DelegatedOperations.ModifiedAt` window begin, end
The number of milliseconds elapsed since January 1, 1970 UTC
Example: 1585967899000

int64
ModifiedToint64

attrf.GetAggregatedRootResponse#

NameDescriptionType
Items[]attrf.AggregatedItem

attrf.GetPaymenProviderResponse#

NameDescriptionType
Providers[]attrf.PaymentProviderInfo

attrf.GetRootsRequest#

NameDescriptionType
StatusIDuint32
RootAddresses[]string
DopHashes[]string
Offsetuint64
Limituint64

attrf.GetRootsResponse#

NameDescriptionType
Roots[]attrf.Root
Offsetuint64
Limituint64
Totaluint64

attrf.Order#

NameDescriptionType
IDstring
Intentstring
Statusstring
RedirectURLstring
Items[]attrf.OrderItem

attrf.OrderRoots#

NameDescriptionType
OrderIDstring
Roots[]string

attrf.PaymentProvider#

NameDescriptionType
IDint32
Namestring
Descriptionstring
Feestring

attrf.PaymentProviderInfo#

NameDescriptionType
IDint32
Namestring
Descriptionstring
Feestring

attrf.PayoutItem#

NameDescriptionType
Accountattrf.Account
Valuestring
Currencystring
Notestring

attrf.PayoutReponse#

NameDescriptionType
IDstring

attrf.PayoutRequest#

NameDescriptionType
EmailSubjectstring
Items[]attrf.PayoutItem

attrf.PostDelegatedOperationsReceiptRequest#

NameDescriptionType
DopHashes[]string
ReceiptIDstring

attrf.PostDelegatedOperationsRequest#

NameDescriptionType
SignedDelegatedOperations[]core.SignedDelegatedOperation
OrderID

Paypal orderID, the order of compensation of delegated operation,
the order must be paid (Status of order is COMPLETED), otherwise, the request is failed.

string

attrf.PostMakePayoutResponse#

NameDescriptionType
Payouts[]attrf.PayoutItem

attrf.PostMakePayoutsRequest#

NameDescriptionType
TxHashes

List of confirmed transaction (that include delegated operation and claim operation) hash to be making payment

[]string

attrf.PostOrderRequest#

NameDescriptionType
RootAddresses

We could use address as string here, attrf should be separated with core, string mean we don't need custom marshaler, would be simpler

[]string

attrf.PostOrderResponse#

NameDescriptionType
OrderIDstring
OrderStatusstring
ApproveURLstring

attrf.PostPublishTransactionRequest#

NameDescriptionType
Transactions[]core.Transaction

attrf.PostPublishTransactionResponse#

NameDescriptionType
FailedTransactions[]attrf.PublishFailedTransaction

attrf.PutDelegatedOperationsStatusRequest#

NameDescriptionType
DopHashes[]string
StatusIDuint32

attrf.QueryContext#

NameDescriptionType
UserAddressstring
IsFacilitatorbool

attrf.Root#

NameDescriptionType
RootAddrstring
Agreementstring
Actionstring
CreatedAtint64
Compensations[]attrf.Compensation

attrf.Transaction#

NameDescriptionType
Hashstring
StatusID

Available : 1-Pending, 2-Published, 3-Publish_Failed, 4-Confirmed, 5-Confirmed_Failed

int32
ErrorMessagestring
DelegatedOpattrf.DelegatedOp

connectors.AccountResponse#

GET /attrace/v1/account

200: success
500: when node is not yet configured

NameDescriptionType
Account

The account which has admin permissions (so the monitor can show this in the UI)

string

connectors.ConfigReponse#

GET /attrace/v1/config

Auth: monitor

NameDescriptionType
ClickoutPath

The url part which handles clickouts
eg: /clickout

string
Account

Admin account configured

string
Network

The network this connector is talking to
eg: betanet

string
MasterTagUrl

The URL where the master tag is available

string
NetworkBroadcastStrategy

How the connector is broadcasting transactions to the network

Options:

  • blocking: broadcast to the network before the user is redirected (and blocks the user).
  • queue: fast background processing, where a background thread or queue is broadcasting to the network near-realtime.
  • cron: slower background processing than queue: some periodic job processes pending transactions, not realtime.
string
TrackingStrategy

How the connector is setting cookies

Options:

  • backend: server module adds the necessary Set-Cookie headers.
  • js: javascript master tag sets the cookies.
string
ConversionStrategy

How the integration tracks conversions

Options:

  • backend: backend module has configuration
  • js: javascript tag handles conversions
string
ProfilingLevel

Additional tracing level for performance

Options:

  • none: no profiling enabled (good)
  • all: all requests are doing profiling (degraded performance)
string
Mode

Similar like NODE_ENV usage in node/webpack projects.

Options:

  • production: guarantees that all develop functionality is disabled.
  • development: debug mode enabled, might expose phpinfo, etc..

Default value when deployed should be "production".

string
ProtocolMode

Some deployments don't support PATCH/DELETE/POST or rewrite requests to GETs

Configuring this allows to bypass these systems. A plugin should do all efforts to avoid this.
That also means, configuring cache exception rules. Otherwise we cause cache misses through monitoring.

Options:

  • restful: (default) the normal protocol
  • fallback: use FallbackRequest instead of normal request flow
string
ApiBasePath

API base path

Default base path is /attrace/v1, changing this to /attr/v2 would result in enabling endpoint like /attr/v2/status.
Recommended to only change if needed
Important: should be without trailing slash. Mounting on root-path '/' is not supported.

string

connectors.ConfigureAccountRequest#

POST /attrace/v1/account

Configure an admin account
Only works when the connector is not already configured

Auth: none, request only works once on startup for initial configuration

200: success
409: already configured

NameDescriptionType
Account

The admin account which is allowed to modify the connector

string

connectors.CreateActionRequest#

NameDescriptionType
Agreement

base32 encoded agreement address

string
Action

action to execute on the agreement, eg: sale

string
ParentRoot

optional base32 encoded parent root address

string
Param

optional action param to be passed to the network. Can occur multiple times, added to the transaction in order how it appears on the url.

[]string

connectors.CreateMonitorRequest#

POST /attrace/v1/monitors

Discovers monitor address from the passed monitor URL
Adds the monitor address in the auth table (so monitor-auth requests are allowed by this account)

NameDescriptionType
DiscoveryUrl

The monitor URL, on this URL /discover can be called and MonitorDiscoverResponse will be returned

string
Account

If set, the discovery can be ignored
The account which is allowed to do monitor requests

string

connectors.DeleteIntegrationConfigRequest#

NameDescriptionType
UniqueId

agreement_address + '-' + delegate_of_address

string

connectors.DeleteMonitorRequest#

NameDescriptionType
Account

Monitor account to remove

string

connectors.ErrorResponse#

JSON model which can be returned on errors

NameDescriptionType
Error

error message

string
Code

optional connector-specific error code

int64
Trace

optional JSON encoded trace data of this error
only available when Mode is on Development

string

connectors.FallbackRequest#

POST /attrace/v1/req

Workaround request for environments which have weird caching plugins installed.
Important to remember that using this interface will leak all bodies into the cache.

A much much better approach is to whitelist the /attrace/v1/* in the caching module and not use this.

NameDescriptionType
Method

GET, POST, PATCH, DELETE, …

string
Path

HTTP path
eg: /attrace/v1/config

string
QueryParams

url-encoded query params
eg: name=123&id=1234

string
Body

JSON-encoded body of the original request

string

connectors.GetIntegrationConfigsRequest#

NameDescriptionType
Next

optional page offset value from the previous response

string

connectors.GetTransactionsRequest#

NameDescriptionType
From

UTC timestamp millis

uint64
To

UTC timestamp millis

uint64
Limit

optional, default 100

uint64
Next

optional page offset value from the previous response

string

connectors.IntegrationConfigsResponse#

GET /attrace/v1/integrationconfigs

Auth: monitor

Query arguments:

  • Next: optional next paging value from the previous response
NameDescriptionType
Items

Configs

[]integrations.IntegrationConfig
Next

The next offset value to pass along, if any

string

connectors.ModifyConfigRequest#

PATCH /attrace/v1/config

Modify a config setting

Auth: admin

NameDescriptionType
Key

Config key

string
Value

Value of this config

string
Reset

True when key override should be reset to it's default value

bool

connectors.MonitorDiscoverResponse#

! ONLY FOR THE MONITOR SERVICE, not the connectors!
GET /discover

NameDescriptionType
Account

The monitor service account, to be granted access to do monitor requests.

string

connectors.MonitorsResponse#

GET /attrace/v1/monitors

Send back list of accounts which have monitor access and their respective URLs

Auth: monitor

NameDescriptionType
Monitors[]connectors.Monitor

connectors.ResetRequest#

POST /attrace/v1/reset

Reset a storage completely (drop table and create new)

Auth: admin

NameDescriptionType
Storage

Storage, can be Config, Transaction, IntegrationConfig, All

string

connectors.StatusResponse#

GET /attrace/v1/status

Auth: monitor

NameDescriptionType
Accountstring
StoreType

Configured with storage
eg: none, mysql, wordpress, …

string
Arch

Sytem architecture
eg: x64, …

string
Language

Runtime language
eg: php, nodejs, …

string
LanguageVersion

Runtime language version
eg: 7.3.11-0ubuntu0.19.10.6

string
Platform

Platform, for platform-specific connectors
eg: wordpress, magento, …

string
PlatformVersion

Platform version
eg: 5.5.1

string
SystemTime

Request system time in millis
eg: 1601730741694

int64
PluginProps

JSON encoded plugin-specific extra props.

string
Version

Version of the connector

string

connectors.Transaction#

GET /attrace/v1/transactions
Get transactions ordered by time desc

Auth: monitor

Query arguments:

  • From: utc timestamp millis
  • To: utc timestamp millis
  • Limit: optional, default 100
  • Next: optional next paging value from the previous response
NameDescriptionType
Key

Hash

string
Value

base64 encoded protobuf binary tx

string
Metadata

JSON encoded private metadata of this transaction
TODO check "null"

string
Error

Error information of last try

string
Retries

Amount of publish to network retries were tried

int32
Synced

Flag if this transaction is published

int32
Ts

Timestamp from the transaction

int64
Id

Int field, can be set to an internal ID. Has no further use.

string

connectors.TransactionsResponse#

NameDescriptionType
Items

Transactions

[]connectors.Transaction
Next

The next offset value to pass along, if any

string

contractprotocol.ContractInfo#

Simple data model for exposing the internal contracts over RPC

NameDescriptionType
Idstring
Versionstring
Descriptionstring

contractprotocol.ListMap#

NameDescriptionType
Values[]contractprotocol.MapValue

contractprotocol.MapValue#

NameDescriptionType
Keyint32
Valuecontractprotocol.Value

contractprotocol.Value#

Simple value type like google type for dynamic values in the contract state.

Contracts can use internally whatever they want to store data efficiently.ly.
Network should avoid contracts with inefficient data storage -- on which in later stage we can do dynamic compensation, if we want.. it's not the goal to rebuild ethereum.

The logic is expected to know what fields to query and requires the contracts to track int32 mappings internally.
When the value is null, the recommended workflow is to delete the value from the state so space is freed.
A value available on the state can be assumed to be set.
If somebody wants to track a null field, which happens less than setting a value, they can store a secondary null marker value.

NameDescriptionType
Strstring
I32int32
U32uint32
I64int64
U64uint64
Boolbool
Blobbytes
ListValues

List of multiple values.

[]contractprotocol.Value
ListMap

Int key:val lookups, list-based to have stable serializer.

contractprotocol.ListMap

core.AccountTransactionCount#

NameDescriptionType
TxCountuint64
Blockbytes
BlockSequencebytes
AccountAddressbytes

core.AccountTransactionCountRequest#

NameDescriptionType
AccountAddress

The address which we want to request

bytes

core.ActionCall#

A single state-change call on a dynamic contract

NameDescriptionType
Action

What method to call. Full method name for clarity, not a hash of the name. Eg: Create, Sale, …

string
Context

An optional list of context values which can be passed around with method calls.
Useful to pass dynamic variables.

[]core.ContextValue
Params

Parameters to the action.

[]contractprotocol.Value
NamedParams

Named params, indexable by the contract.

contractprotocol.ListMap

core.AddressMsg#

NameDescriptionType
AddressTypeValueuint32
EncodedValuestring

core.AddressStatesRequest#

NameDescriptionType
Hash

Use string because our gate way support in query param, custom marshaller not worked for query param
Keep this to support forward solution, working with old request

string
Hashes

Support multiple hashes

[]string

core.AddressStatesResponse#

NameDescriptionType
AddressStates[]core.AddressState

core.Airport#

Airport info

NameDescriptionType
iata

lowercase to work with json

string
latdouble
londouble

core.AnnotatedTransaction#

NameDescriptionType
Transactioncore.Transaction
Receiptcore.TransactionReceipt
BlockHashbytes
BlockSequenceuint64

core.AuthResponse#

NameDescriptionType
Challenge

Challenge the signature relates to

bytes
Signature

Signature of the challenge

bytes

core.Block#

NameDescriptionType
Header

Block metadata header

core.BlockHeader
Transactions

Transactions processed in this block.
This includes failed transactions.

[]core.Transaction
Signatures

Signature data of all transactions
These signatures can be dropped from storage when blocks are sufficiently confirmed by the network

[]core.BlockTransactionSignatures
Receipts

Transaction receipts
One for every tx in Transactions

[]core.TransactionReceipt
TracingContext

Optional tracing info, use to carry tracing context to another node

bytes

core.BlockAnnotations#

The BlockAnnotations is a structure to support properties to share between multiple witnesses, which are not required to be stored.
Having them on the block header shows that 2f+1 witnesses agree on the data.
Nodes can ignore validation of these optionals when syncing and only need to verify them when in hot consensus.
Initial use case is gossipping failed transactions and making it possible to verify that information.

NameDescriptionType
FailedTransactions

Failed transactions which can be removed from the mempools on the network.

[]core.EvaluatedTransaction

core.BlockBySequenceRequest#

NameDescriptionType
Sequenceuint64

core.BlockBySequenceResponse#

NameDescriptionType
Blockcore.Block

core.BlockHeader#

BlockHeader contains all block metadata to allow verification
Header is sent once block is completed and confirms a fully generated block (who's chunks have already been broadcasted)

NameDescriptionType
Sequence

Ever-increasing number of this block in the chain.

uint64
Timestamp

Timestamp millis this block was generated

uint64
Witness

Address of the witness that generated this block.

bytes
Hash

Hash of this block
hash(sequence, timestamp, parentHash, merkleRoot, producer)

bytes
PreviousHash

Hash of the previous block.

bytes
MerkleRoot

Merke root of transactions and signatures.

bytes
Signature

Signature by the producer of this block.
sign(append(sequence, timestamp, parentHash, hash, merkleRoot, producer))

bytes
Fees

Total amount of fees collected for processing the embedded transactions

bytes
ReceiptsRoot

Merkle root after processing the receipts

bytes
AnnotationsRoot

Merkle root of the annotation info we share with the other witnesses.
Before committing to a block, witnesses need the annotations to validate the block.
It's useful for storing and verifying volatile data, like failed transactions.
When they are syncing (and thus not voting for), it's not required for witnesses to validate this (since the info might already be flushed from the network).

bytes

core.BlockTransactionSignatures#

NameDescriptionType
Signature

Transaction signature

bytes

core.BlockchainHashes#

Lightweight model for client/channel validation.
Can send up to 65k block hashes at a time (4 MB).

NameDescriptionType
Confirmed

Confirmed hashes are to be processed first.
Confirmed hashes are part of the chain incl. the last consensus block.

[]bytes
Unconfirmed

Unconfirmed chain are not yet consolidated behind a last consensus block.
They can be used, but should not yet be trusted.
These blocks can still be reverted.
When syncing a new chain, this will probably be empty.

[]bytes

core.BlocksRequest#

NameDescriptionType
Hashes[]bytes

core.CachedBlock#

Structure for sharing blocks during consensus and sync amongst the witnesses.
We want to avoid serialization overhead and allow witnesses to share bytes streamed directly from disk.

NameDescriptionType
RawBlockbytes
RawBlockAnnotations

Optional block annotations

bytes

core.ChallengeInfo#

NameDescriptionType
PeerAddr

Address of connecting client

bytes
TTL

TTL of the challenge

uint64

core.ChallengeRequest#

NameDescriptionType
PeerAddr

Address of connecting client

bytes
Challengebytes

core.ChallengeResponse#

NameDescriptionType
Challengebytes
SignedChallengebytes

core.ChannelStatus#

NameDescriptionType
ChannelAddressbytes
peers[]core.ChannelPeerStatus

core.Commit#

NameDescriptionType
BlockHashbytes
PeerAddressbytes
PeerSignaturebytes
ProducerAddressbytes
ProducerSignaturebytes

core.Compensation#

NameDescriptionType
TxHashbytes
TxOpuint64
Beneficiarybytes
Valuecore.CompensationValue

core.CompensationValue#

NameDescriptionType
Value

Encoded as bigint big endian

  • ATTR: would saved as ACES values (default 18 decimal supported)
bytes
ConversionValue

Encoded as bigint big endian. Store the original value defined in the contract.

  • Fiat money: saved as ACES values (default 10 decimal supported)
  • ATTR: saved as ACES values (default 18 decimal supported)
bytes
ConversionCurrency

Deprecated. Keep this field to avoid breaking when validating block.

string
ConversionRate

Conversion rate from ConversionValue to ATTR token. Encoded as bigint big endian as ACES values (6 decimal supported)
Ref: https://gitlab.com/attrace/docs/-/blob/develop/docs/guides/token-rates.md

bytes

core.ConsensusEvent#

NameDescriptionType
PrePreparecore.PrePrepare
Preparecore.Prepare
Commitcore.Commit
ViewChangecore.ViewChange
NewViewcore.View

core.ContextValue#

NameDescriptionType
Name

Property name, eg: UserAgent

string
Value

The actual value

bytes
ValueType

Value serializer

int32

core.DelegatedOperation#

NameDescriptionType
Operation

Operation to be executed by delegatee

core.Operation
Account

Owner address of operation. The one who sign the DelegatedOperation. This could be account address or operational key address.

bytes
Delegatee

Address of delegatee

bytes

core.DiscoveryManifest#

NameDescriptionType
SnapshotTimeuint64
Witnesses[]core.PeerInfo
Airports

List of current airports

[]core.Airport

core.EdgeLocation#

NameDescriptionType
Latitude

Latitude indication where this node is running (x 100000)

int32
Longitude

Longitude indicatio nwhere this node is running (x 100000)

int32
NearestSubdivision

Nearest subdivision within a country (state/province), by distance to center of the subdivision.
As ISO3166-2 state or province code. Eg: US-CA, NL-NH, …
See https://en.wikipedia.org/wiki/ISO_3166-2 and click the country.

string

core.EvaluatedTransaction#

A structure to share a transaction with it's execution receipt

NameDescriptionType
StagePosition

Position in the block transactions where we tried staging this transaction (and failed)
This required to achieve stable evaluation behavior across witnesses, so they work in the same order

uint32
Transaction

The original transaction

core.Transaction
Receipt

The receipt detailing the failure reason

core.TransactionReceipt

core.FullNodeData#

NameDescriptionType
PeerInfocore.PeerInfo
Gossipcore.Gossip
BlockHeadercore.BlockHeader
Transactioncore.Transaction

core.GetAccountBlockHashesRequest#

NameDescriptionType
AccountAddressstring
FromBlockuint64
ToBlockuint64
Limituint64
GetLatestbool

core.GetAccountBlockHashesResponse#

NameDescriptionType
BlockHashes[]bytes

core.GetAccountTokenRateResponse#

NameDescriptionType
Currency

Currency symbol

string
Rate

Rate of currency by ratio 1 / 1000000

uint64

core.GetAccountTokenRatesRequest#

NameDescriptionType
AccountAddressstring

core.GetAccountTokenRatesResponse#

NameDescriptionType
UpdateTime

Lastest update of account token rates (UNIX timestamp)

uint64
Rates

Rates by currency, notes: rate have a ratio 1 / 1000000 with 1 currency

[]core.GetAccountTokenRateResponse

core.GetActionsByParentRootRequest#

NameDescriptionType
Addressstring
Timezonestring
Actions

List of included actions, if nothing passed, fetching all

[]string

core.GetActionsByParentRootResponse#

NameDescriptionType
Actions[]core.Action
ParentRootcore.Action

core.GetAggregatedRootDataRequest#

NameDescriptionType
Agreements

List agreement address to query, base32 encoded string

[]string
FromTime

UTC time millis search window begin
Example: 1585967899000

int64
ToTime

UTC time millis search window end, exclusive.
Example: 1585967899000

int64

core.GetAgreementsRequest#

NameDescriptionType
Partybytes

core.GetAgreementsResponse#

NameDescriptionType
Agreements[]core.Agreement

core.GetCompensationStatsRequest#

NameDescriptionType
AccountAddress

The user account address to query, base32 encoded string

string
FromTime

UTC time millis search window begin
Example: 1585967899000

int64
ToTime

UTC time millis search window end, exclusive.
Example: 1585967899000

int64

core.GetContractsRequest#

NameDescriptionType

core.GetIdxAccountTokenRatesRequest#

NameDescriptionType
Accountstring

core.GetLatestRootRequest#

NameDescriptionType
Agreements

Agreement address to include, as base32 encoded strings

[]string
Timezone

Timezone for filter, used to calculate time when filter on specific timezone
This has to be a valid value according to https://golang.org/pkg/time/#LoadLocation
Example: UTC, America/Los_Angeles, Europe/Amsterdam

string
Actions

Type of root action, can be click, lead, sale

[]string
Limit

Amount of requested record

int64
Statuses

List action statuses being required

[]string

core.GetOperationHistoryRequest#

NameDescriptionType
Agreements

Agreement addresses to include, as base32 encoded strings

[]string
FromTime

UTC time millis search window begin
Example: 1585967899000

int64
ToTime

UTC time millis search window end, exclusive.
Example: 1585967899000

int64
Timezone

Timezone for filter, used to calculate time when filter on specific timezone
This has to be a valid value according to https://golang.org/pkg/time/#LoadLocation
Example: UTC, America/Los_Angeles, Europe/Amsterdam

string
TimeAggregation

What time grouping, default is day.
Supported: day

string
Operations

Optional list of operation types to include. Eg: root, actioncall.

[]string

core.GetRootHistoryRequest#

NameDescriptionType
Addressstring
Timezonestring

core.GetRootsByAddressesRequest#

NameDescriptionType
Addresses[]string
Currencies

Type of fiat money
Currently, USD is available
Missing this field == Return fiat money value of all currencies by default

[]string

core.GetRootsRequest#

NameDescriptionType
Agreements

Agreement address to include, as base32 encoded strings

[]string
Timezone

Timezone for filter, used to calculate time when filter on specific timezone
This has to be a valid value according to https://golang.org/pkg/time/#LoadLocation
Example: UTC, America/Los_Angeles, Europe/Amsterdam

string
Actions

Type of root action, can be click, lead, sale

[]string
Limit

Amount of requested record

int64
Offset

Amount of skipped record

int64
Statuses

List action statuses being required

[]string

core.GetSupportedCurrenciesResponse#

NameDescriptionType
Currencies[]core.Currency

core.GetViewsRequest#

NameDescriptionType
ViewOffsetID

View should be higher than

uint64
BlockGTEOffsetSeq

Optional optimization >= this block offset (views can base off the same block)

uint64

core.Gossip#

Push of info from one node to another

NameDescriptionType
Time

Source peer time when the message was generated

uint64
Peers

List of all known witnesses + info
These are the commandline-seeds + top-1000 according to local chain copy

[]core.PeerInfo

core.HandleConsensusEventsRequest#

NameDescriptionType
Events[]core.ConsensusEvent

core.HashMessage#

NameDescriptionType
Hashbytes

core.HashQueryParam#

NameDescriptionType
Hashstring

core.HotConsensusDebugResponse#

NameDescriptionType
LastCommitBlockcore.BlockHeader
Phaseint64
Sessioncore.ConsensusSession
BlocksEvents[]string
Actions[]string

core.LatestBlocksRequest#

NameDescriptionType
Sequenceuint64
Limituint64

core.LatestBlocksResponse#

NameDescriptionType
Blocks[]core.LatestBlock

core.LatestRootResponse#

NameDescriptionType
Sequence

Sequence indicaate a package number sent through ws

int64
Roots[]core.Root
TotalRecord

The Amount of records in table roots,
will be fetched in the first loading time to init the value

int64

core.LatestTransactionsRequest#

NameDescriptionType
Limituint64

core.LatestTransactionsResponse#

NameDescriptionType
LatestTransactions[]core.LatestTransaction

core.Limit#

NameDescriptionType
Countuint64
StartingBlockbytes
UntilBlock

Optional block after which the result will end

bytes

core.MempoolInfoResponse#

NameDescriptionType
Pagingcore.Paging
PendingTransactionCountint32
PendingTransactions[]core.Transaction

core.MultiHashQueryParam#

NameDescriptionType
Hashes[]string

core.NetworkStatusResponse#

NameDescriptionType
Witnesses[]core.PeerInfo
Candidates[]core.PeerInfo
ConfirmedChainTipcore.BlockHeader

core.NodeStatusResponse#

NameDescriptionType
Witnessbool
Candidatebool
ConfirmedChainTipcore.BlockHeader
PeerAddressstring
LagInSecuint64

core.Operation#

Individual operations
A transaction can have many (eg: distribute value to multiple accounts from one account; or add 100 roots at once)

NameDescriptionType
Value

The actual operation

core.OperationValue
SecureVerifyHashes

Hashes for verifying the secure actions in the channels before executing them.
Multiple hashes can be listed, which can be required for sharing granular content in the channels (one hash should match).

[]bytes

core.OperationActions#

NameDescriptionType
RootActions

Root Actions which can be verified against Operation.secureHashes

[]core.ActionCall

core.OperationAssignTokenLease#

This will allow another party to consume a specific amount of tokens from another account.
This is not locking the tokens on the network, it allows a contract to consume tokens from another account's balance for network operation tasks.
If there is an outstanding lease, the amounts are summed and available immediately.

NameDescriptionType
LeaseValue

The amount to add to the lease
It's required for the Provider to have this amount of token balance at the time of processing.

bytes
Provider

The party who is leasing (and is required to have this balance)

bytes
Beneficiary

Who can consume the leased tokens

bytes

core.OperationChangeWitnessCandidacy#

Created by a peer when they are up for election
The candidate should have 1000 ATTR, which will be locked

NameDescriptionType
Candidate

Address of the candidate

bytes
UpForElection

Set to true, if candidate is up for election

bool

core.OperationClaimRootCompensation#

OperationClaimRootCompensation would sent ATTR from SourceAddress to Facilitator to receive fiat money
NOTE: Get value need to claim from rootState.Root.Compensation. This would ONLY work when this op in the same tx that have compensation

NameDescriptionType
Root

Root address which makes the compensation

bytes
SourceAddress

SourceAddress owner of the compensation

bytes
Facilitator

Address of the facilitator would handle the compensation

bytes

core.OperationCompensation#

Compact

NameDescriptionType
Beneficiary

Who receives the compensation, a member of the agreement.
Maps to the index (0-based) in the immutable CreateAgreement.Parties.

uint32
Value

Encoded as bigint big endian

  • ATTR: would saved as ACES values (default 18 decimal supported)
bytes
Currency

Deprecated. Keep this field to avoid breaking when validating block.
In new flow, the value is always ATTR value. Old data still have Currency values.

uint32
ConversionValue

Encoded as bigint big endian. Store the original value defined in the contract.
Values are multiplied with 10^10, so they keep 9 digits correct.

bytes
ConversionCurrency

1=USD, 2=EUR, … See currency.go#L21

uint32
ConversionRate

Conversion rate from ConversionValue to ATTR token. Encoded as bigint big endian as ACES values (6 decimal supported)
Ref: https://gitlab.com/attrace/docs/-/blob/develop/docs/guides/token-rates.md

bytes

core.OperationConfirmAgreement#

This will sign an pending agreement on the network.

NameDescriptionType
Agreement

Agreement which we confirm

bytes

core.OperationCreateAgreement#

This will create an agreement on the network.

NameDescriptionType
Parties

All involved parties, who all need to approve the contract to get it started.

[]bytes
ContractHash

Agreement contract bytecode verification hash. sha256(compiledWasmCode, hashNonce).

bytes
ContractByteCode

Byte Code of the contract

bytes
ConfirmationDueInHours

The amount of hours until unconfirmed agreement will be purged

int32
ContractId

Which contract is used from the contract library

string
Arguments

Dynamic initialization arguments for the contract
This can hold things like customized commission rules, revsharing rules, pricing rules, product rules, …
The total size of all arguments combined should be below 1KB.
TODO: validation on 1Kb

contractprotocol.ListMap
CompensationCurrency

Currency in which compensations are calculated.
0=NONE | 1 = USD | 2 = EUR | …

uint32

core.OperationCreateRoot#

Register a root type, a piece of data which can be tracked over time and have state changes
The name comes from something which grows into different states over time.

NameDescriptionType
RootOwner

The creator defines this and ideally this is the pubkey of a unique keypair (or derived).
For space efficiency reasons, we don't track checksum and type here. We don't expect this hash to be copied manually by users.
Keys can already exist and a single key can manage multiple roots

bytes
Agreement

Agreement this root belongs to

bytes
TTL

Field to control the amount of hours the network tracks this root.
Required to set, it impacts cost of operation.
If dependant operations require this root after it has been purged, those transactions will fail.
Example: a lead which hasn't converted in 3 months time, can be dropped.
Unit: hours.

uint32
SourceAccount

Source account generating the root (click, tap, trackable something)
Will be somebody listed in OpCreateAgreement.rootCreators
This is an internal type and should be emptied when storing the operation.

bytes
Allowance

Since the account who creates the root is currently paying for the processing, it's important they can set a limit how much work can be done.
With every on-chain operation, this amount decreases with the amount of fees. Once there is insufficient allowance, the transaction will fail.
In a later stage we can allow allowance increases.

bytes
ActionCallcore.ActionCall
ParentRootAddressbytes

core.OperationModifyAccountAccess#

replaces any previous access configuration for the targeted accounts + scopes

NameDescriptionType
BlockSequence

(Optional) After this block sequence, operational key will be revoked

uint64
GrantScopecore.AccessScope
RevokeScopecore.AccessScope

core.OperationReceipt#

NameDescriptionType
Fees

Amount of fees in ATTR consumed by processing this operation.

bytes
FeeOwner

Optional field to indicate alternative fee owners.
Setting this to Transaction.SourceAddress (when no TransactionReceipt.FeeOwner is configured) or the TransactionReceipt.FeeOwner will make the block invalid.

bytes
Compensations

Compensations generated by executing this operation

[]core.OperationCompensation
StateDeltas

State changes done during exeuction of this operation.
If a value is nil, the value was removed.

contractprotocol.ListMap

core.OperationRevokeTokenLease#

This will revoke any open token lease from one account to another with any remaining lease value, effective immidiately.

NameDescriptionType
Provider

The party who is leasing (and is required to have this balance)

bytes
Beneficiary

Who can consume the tokens

bytes

core.OperationRootActionCall#

NameDescriptionType
RootAddress

The address of the root

bytes
Agreement

Agreement which will process this.

bytes
SourceAccount

Source account generating the action

bytes
ActionCallcore.ActionCall

core.OperationStake#

Stake (=vote) for a set of witnesses. This will replace any previous Stake operations you had active on the network.
This means "I want these candidates to become elected witnesses".
1 token Value == 1 vote.

NameDescriptionType
StakedValue

Total amount of value that gets staked; uint256
When the network accepts this vote, the tokens will be locked.

bytes
Candidates

The witnesses which will receive equal votes.

[]bytes

core.OperationTransferValue#

Transfer ATTR value in aces from account to another
This implies to origin address is allowed to send this amount

NameDescriptionType
FromAddr

TODO validate if this can be binary

bytes
ToAddr

TODO validate if this can be binary

bytes
Value

The value transferred; uint256

bytes

core.OperationUnstake#

When the network accepts this release, the value will remain locked for a few days.
To change staked witnesses, another StakeWitness operation needs to be created.

NameDescriptionType
ReleaseValue

Amount of funds to be released.

bytes

core.OperationUpdateAccountTokenRates#

NameDescriptionType
Time

time when operation generated

uint64
AccountAddress

SourcesAccount address will get update token rates

bytes
Rates

rates list rate by given currency

[]core.TokenRate

core.OperationValue#

Different operations possible

NameDescriptionType
TransferValuecore.OperationTransferValue
ChangeWitnessCandidacycore.OperationChangeWitnessCandidacy
Stakecore.OperationStake
Unstakecore.OperationUnstake
CreateAgreementcore.OperationCreateAgreement
ConfirmAgreementcore.OperationConfirmAgreement
CreateRootcore.OperationCreateRoot
RootActionCallcore.OperationRootActionCall
AssignTokenLeasecore.OperationAssignTokenLease
RevokeTokenLeasecore.OperationRevokeTokenLease
UpdateAccountTokenRatescore.OperationUpdateAccountTokenRates
ModifyAccountAccesscore.OperationModifyAccountAccess
SignedDelegatedOperationcore.SignedDelegatedOperation
ClaimRootCompensationcore.OperationClaimRootCompensation

core.Operations#

Serialization helper

NameDescriptionType
Values[]core.Operation

core.Paging#

NameDescriptionType
Limitint32
Offsetint32

core.PeerInfo#

Info broadcast

NameDescriptionType
Address

Address (key) of this node.

bytes
Host

Advertised gRPC hostname.

string
Port

Advertised gRPC port other peers can use to connect to this peer.

uint32
ApiHost

Optional additional API host override, if any
We assume SSL by default

string
ApiPort

Optional additional API port override, if any
We assume SSL by default

uint32
Time

Local time in milliseconds when this peer info was generated.

uint64
Signature

Signature of above data, allowing this object to be gossipped and trusted.

bytes
Location

Optional geo location indication where this peer is located, used for ping-less server selection

core.EdgeLocation

core.PeerStatus#

Used for attr-top, should be more generic.
Mixes in with peer status and node status info… pick one or query node status info as well.

NameDescriptionType
Typestring
Addressbytes
LastConfirmedBlockcore.BlockHeader
IsWitnessbool
IsCandidatebool
LastErrorcore.PeerError
LastWarncore.PeerError
ServerUpdateStreamCountuint32
Channels[]core.ChannelStatus
TxInTenSecCountuint32
TxCountuint64
Threadsuint64
GitCommitstring
Versionstring
CurrentRoundSessionstring
CurrentProducerstring
NextProducerstring
LastViewHashstring
MempoolTxPendingCountuint64
MempoolTxUnconfirmedBlocksCountuint64
StartTimeuint64
OpCountuint64

core.PrePrepare#

NameDescriptionType
Headercore.BlockHeader
ValidatorAddressbytes
ValidatorSignaturebytes
PeerAddressbytes
PeerSignaturebytes
Viewcore.View

core.Prepare#

NameDescriptionType
BlockHashbytes
PeerAddressbytes
PeerSignaturebytes
ProducerAddressbytes
ProducerSignaturebytes

core.RawData#

NameDescriptionType
Databytes

core.RawDataList#

NameDescriptionType
Datas[]core.RawData

core.ResultSet#

Dynamic nestable structure for all query resultset handling.

NameDescriptionType
Dimensions

Ordered list of field metadata for the results present in the result set.

[]ResultSet.Dimension
Metrics

Ordered list of field metadata for the results present in the result set.

[]ResultSet.Metric
Results

Data results

[]ResultSet.Result

core.SearchRequest#

NameDescriptionType
Patternstring
Limituint64

core.SearchResponse#

NameDescriptionType
Results[]core.SearchResult

core.SecureTransaction#

The SecureTransaction is to be shared between parties directly over an encrypted channel.

NameDescriptionType
Transaction

The original transaction, which is also broadcasted to the public chain.

core.Transaction

core.SignedDelegatedOperation#

NameDescriptionType
DelegatedOperationcore.DelegatedOperation
Signature

Verify signature of DelegatedOperation

bytes

core.StateAccountTokenRates#

NameDescriptionType
UpdateTimeuint64
Rates[]core.TokenRate

core.StreamReceiptsRequest#

NameDescriptionType
Sequence

Optional sequence where to start, when omitted, starts from tip of the chain
-1 starts from tip of chain, -2 starts from tip-1000

int64
TransactionHashes

optional tx hashes to filter for, strings because grpc gateway doesnt support custom serializers on the URL

[]string

core.SyncBlocksRequest#

NameDescriptionType
OffsetBlockHashbytes
Limitint32

core.Token#

NameDescriptionType
ExpireTime

Request time + 120s

uint64
Address

The source address

bytes
Signature

Signed by the server

bytes

core.TokenRate#

NameDescriptionType
Currencyuint32
Rateuint64

core.TokenRequest#

NameDescriptionType
OriginalChallenge

originalChallenge contains original challenge from server

bytes
ClientAddrbytes
SignedChallengebytes

core.TokenResponse#

NameDescriptionType
Tokenbytes

core.Transaction#

Transaction is the building block of the network.
It contains the operations with state modifications or other actions to be handled by the witnesses.

NameDescriptionType
Hash

Hash of this transaction

bytes
SourceAddress

Source defines the address which generated and signed this transaction.

bytes
Timestamp

Timestamp millis when this TX was created on the source system

uint64
Operations

Operations which should be applied to the blockchain state.

[]core.Operation
Signature

Signature guarantees the Transaction originates from the source account
It contains the result of Sign(hash, timestamp, sourceAddress, operations…)
When consolidated into a block, these are stored at the block level

bytes
TracingContext

Optional tracing info, use to carry tracing context to another node

bytes
Nonce

Incremental number by signing account providing processing order to messages.
It's part of the hash and network will keep tx in mempool until all previous nonces are processed.

uint64
CreateAccount

Optional, who created the transaction on behalf of the owner. When this field is set, it will be used for verifying the signature. Just like the signature, `CreateAccount` might be dropped in consolidation of the chain.

bytes
SecureHash

SecureHash is set by connector in order to verify transaction metadata context

bytes
IsPulse

Mark true if this is transaction is part of the Pulse system

bool

core.TransactionReceipt#

Execution result of a Transaction

NameDescriptionType
Status

Execution status of the transaction. False = failed. True = success.

bool
FeeOwner

When null, it means the fee owner is Transaction.SourceAddress, this is inferred by default.
Optional to override the fee owner at transaction level.
Setting this to Transaction.SourceAddress will make the block invalid.

bytes
OperationReceipts

Allows to override specific behavior at operation level.

[]core.OperationReceipt
ErrorOperation

Which operation caused the error
The first operation which fails, stops processing

uint32
ErrorCode

Error code, can be set to an error string indicating problem. Eg: INSUFFICIENT_TOKEN, CONTRACT_MISSING, …

string
ErrorMessage

Optional error message and variable dump. Can be left empty.

string

core.TransactionResponse#

NameDescriptionType
Txcore.Transaction
ProcessedInBlockHashbytes

core.ValidateBlockRequest#

NameDescriptionType
Blockcore.Block
Viewcore.View
BlockAnnotationscore.BlockAnnotations

core.ValidateBlockResponse#

NameDescriptionType
Signaturebytes
ChainTip

In case of failed validation, we send the chain tip of the remote node at time of validation.
Producer can use this to make a decision how to handle it's validation.
Eg, if the node is 1 block behind, it can wait + retry; if it's 10 blocks behind, it can switch validator; if the node is in the future, it can trigger shadow consensus; ….
If validation is successful, this field will be null

core.BlockHeader

core.View#

Broadcasted by the producer-elect when the network agrees on him being the new producer
New view == New producer

NameDescriptionType
ViewID

The View ID of the round we are about to launch

uint64
Producer

Target of this message ( witnesses | blockhash ) mod n

bytes
Validator

Who should validate the round (witnesses-validator) mod n

bytes
LastBlock

Hash of the last committed block we have
This allows to verify that the new view is correct and relevant

core.BlockHeader
ProduceAmount

Nr of blocks planned to be generated by this witness

uint32
ViewChangeRequests

The viewchanges
These proof that a view is valid or not
Nodes receiving these verify these against elected witness status at that point in chain

[]core.ViewChange

core.ViewChange#

ViewChange = node requesting to change producer
ViewChanges are alive and only valid for a short time, so no need to store them.

NameDescriptionType
NewViewID

Ever increasing number -- gaps can exist on the network of this when producers are down during re-election.

uint64
Producer

What node should produce next according to this witness

bytes
Validator

What node should validate next according to this witness

bytes
LastBlock

Hash of the last committed block we have
This allows to verify that the new view is correct and relevant

bytes
ProduceAmount

Nr of blocks planned to be generated by this witness

uint32
LastBlockProofCommits

Proof that 2f+1 of the network is committed to this point
TODO add commit proofs to genesis block generation

[]core.Commit
Witness

Address of witness who has voted for this

bytes
Timestamp

Used by the view change algorithm to calculate network-relevant view change time offset

uint64
Signature

Sig of this msg

bytes

core.ViewList#

NameDescriptionType
Views[]core.View

core.Void#

Empty placeholder structure

NameDescriptionType

core.WitnessList#

Node's current list of known witnesses

NameDescriptionType
Witnesses

List of known elected witnesses

[]core.PeerInfo
Candidates

List of known candidates

[]core.PeerInfo

integrations.IntegrationConfig#

NameDescriptionType
Role

Role of this integration
Can contain values like "advertiser", "publisher", "consultant", …

string
Agreement

The agreement address this configures

string
OperationalKey

Private key of an Account who can sign the transactions for this agreement.
Normally this account has received permissions on the network to create the required actions.
Previously: "Account"

string
DelegateOf

Who is the controlling account of this service account.
Required for publishing correct transactions.

string
RootActionConfigs

Configs how to handle different root actions

[]integrations.RootActionConfig
DefaultActionRootType

The default root to create when an action request is fired without
Previously: defaultaction

string
ExpireDays

The number of days actions can be published since their root creation.
Modules filter out expired events to avoid broadcasting invalid transactions.
Cookie logic can use this to set correct cookie expiry times.
Previously: "cookiedays".

int32
UrlActions

URLs which need to trigger actions

[]integrations.UrlAction
Name

Display name used in the UI

string
Metadata

This contains informative properties not used by our integration.
Use as last resort. Extend datamodel when required.

[]integrations.KeyValue

integrations.KeyValue#

NameDescriptionType
Keystring
Valueintegrations.Value

integrations.ListMap#

NameDescriptionType
Values[]integrations.KeyValue

integrations.RedirectUrl#

NameDescriptionType
Url

The URL to which we redirect.

string
AliasId

Alternative URL-safe identifier that will redirect to this URL.
Previously mapped from 'hashes'

string

integrations.RootActionConfig#

NameDescriptionType
RootType

The root type this configures
Eg: click, sale, …

string
RedirectUrls

Redirect URL configurations

[]integrations.RedirectUrl

integrations.UrlAction#

URL which triggers an action

NameDescriptionType
Url

Url part which is the trigger
Eg: /sale

string
Action

Action which is triggered
Eg: sale

string

integrations.Value#

NameDescriptionType
Strstring
I32int32
U32uint32
I64int64
U64uint64
Boolbool
Blobbytes
ListValues

List of multiple values.

[]integrations.Value
ListMap

Int key:val lookups, list-based to have stable serializer.

integrations.ListMap

Scalar value types#

Language-specific scalar type mapping reference.

TypeNotesGoPHPPythonJavaC++
doublefloat64floatfloatdoubledouble
floatfloat32floatfloatfloatfloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32integerintintint32
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64integer/stringint/longlongint64
uint32Uses variable-length encoding.uint32integerint/longintuint32
uint64Uses variable-length encoding.uint64integer/stringint/longlonguint64
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32integerintintint32
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64integer/stringint/longlongint64
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32integerintintuint32
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64integer/stringint/longlonguint64
sfixed32Always four bytes.int32integerintintint32
sfixed64Always eight bytes.int64integer/stringint/longlongint64
boolboolbooleanbooleanbooleanbool
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringstringstr/unicodeStringstring
bytesMay contain any arbitrary sequence of bytes.[]bytestringstrByteStringstring

Developers#

note

These docs are generated from the core/* protobuf definitions.
Changes should be done in the source files or will be overwritten.