Engineering Decision Records
001-record-engineering-decisions
"By the time one ponders the consequences of a particular decision, the people who made that decision may not be around the table anymore."
002-linux-development-model
"We propose to adopt a development process similar to Linux to encourage decentralized contributions and maintain the project's ethos of decentralization."
003-git-etiquette
"In a large project with multiple contributors, it is necessary to establish some git etiquette to keep the project maintainable."
004-amaru-design-framework
"The ambition of the project is to build a new fully interoperable block-producing node for improving the overall performance the Cardano blockchain."
005-amaru-maintainers-committee
"In order to manage the decision making on the project and have a compelling product oversight, Matthias and Santiago want to extend their maintainers committee's responsibilities to other members."
006-design-phase-documentation
"The Amaru team submitted a proposal with a list of scopes related to the project and describing a specific way of administrating the budget, this is now reflected into the ways of working of the project."
007-observability
"We would like the codebase to organize the metrics it tracks in a simple, consistent and modular way, such that each module or crate can own a subset of the metrics, while at the same time being consistent and discoverable through reading the code."
008-logbook
"Additionally, new developers to the project, or developers that have spent some time away from the project, will have a repository of knowledge to get quickly reacquainted with the progress of the project."
009-avoid-primitive-obsession
"A newtype is recommended where the primitive type has a particular and well-established meaning that exists not only in the local code scope, because this implies that uses of the primitive type will overlap with other semantics that shall remain distinct."
010-ledger-validation-context
"To overcome this, we introduce an extra step which we call preparation, and whose role is to traverse the block once to identify which entities will be needed by the validation rules, thus ensuring that the data needed down the line is identified and fetched from the storage in a single batch."
011-deterministic-simulation-testing
"The state-of-the-art to deal with the testing problem is to generate test"
012-interaction-between-consensus-and-ledger
"On the other hand, the main complexity of the ledger lies in its state management so that it can efficiently support the various required calculations for performing the business function of the Cardano blockchain."
013-error-handling-strategies
"Use #[from] Box<dyn std::error::Error + Send + Sync> if you need to embed arbitrary foreign errors of different kinds;"
014-time-in-amaru
"The current state as well as the history of Cardano do not require us to implement the ability to change the slot length."
015-recording-cardano-metrics
"As a result, we had to compromise and fallback to the MetricsEvent enum solution, which still limits the amount of changes needed to add/remove metrics."
016-treasury-management-acceptance-process
"To complete the transparency aspect of the process, the scope contributor will: Upload a redacted invoice to IPFS, Upload a redacted agreement to IPFS and link the invoice and the agreement in the transaction's metadata"
017-version-and-migrate-db
"Migration tools are rife in the RDBMS world (see this page for a Postgres-centric list) and migration process is typically handled by storing versions and migration scripts results and metadata in the database itself to make it self-checkable, with actual migration code integrated in the executable"
018-amaru-maintainers-committee
"Each committee member shall own a budget pertaining to its scope, and administrate that budget over the course of the year alongside other members of the committee."
019-guidelines-for-writing-cli
"This EDRs defines guidelines to follow when building CLI in the context of the Amaru project to keep the CLIs tidy and maximise the user experience."
020-bump-arenas-and-workarounds
"It is similar to Bump in that you can push/alloc with only a shared reference, and in that it never moves items once they've been allocated so it can have long lived shared references to items."
021-switching-to-own-mini-protocols
"Conformance of the network part is statically ensured by the underlying state machine structure, while proper interaction of the decision-making part with the network is regulated by runtime checks."
022-treasury-management-acceptance-process
"The acceptance process is deemed finished when the scope owner (accountable of the work done) updates the [amaru-treasury Journal][] with an entry stating that he accepts the work done and includes all the details related to the payment in the metadata of the transaction (IPFS of the contract, IPFS of the invoice, description of the intent)"
023-code-annotations
"to draw the attention of the reader to a particular design decision or consequence"
024-peer-handling-infrastructure
"Most of these aspects are internal to a node while some others are observable to peers (the spec was written with only the Haskell implementation in mind, meaning that peers would run either the same software or a slightly different version)."
025-release-and-distribution-workflow
"If a same-version draft release already exists, the workflow shall delete the stale draft release and its tag before creating a fresh draft."
026-tracing-span-design
"forward upon successful decoding of the header in the trackpeers stage and closing that span in the selectchain stage, either upon seeing that the header is not on the best chain candidate or upon receiving the block validation result (which is slightly after adopting the block but typically before communicating the new tip to downstream peers)."
027-ada-only-contracts-with-amaru
"While this is "part of the game" when being paid in ada, we are also conscious of the risks that come with using ada as a mean of payment."
028-contingency-allocation
"167$ for the minimum ₳ value that can secure us the scopes mentioned, every scope owner has to trade (at least) to that level to secure the amounts to be paid to our partners."
029-runtime-stake-summaries-and-on-demand-rewards-distributions
"The ledger pays an additional reconstruction cost when rewards start, but that cost is isolated to the rewards path and avoids carrying large maps for the rest of the epoch."
030-consensus-performance-resource
"Peer lifecycle: recordadvertisability (successful handshake: sets everconnected, records peer-sharing willingness; overwrites advertisability), recordconnectionfailure (increments failure counter telemetry, raises connection malus; does not set everconnected), clearpeeravailability (disconnect / no remaining live connection; scores and reputation kept, claims cleared), peeradversarial (adversarial ban: claims and scores cleared, entry retained with adversarial = true and prior everconnected / failurecount / last advertisable, plus adversarial malus impulse; not a generic erase)"
Showing 30 of 35 EDRs