mAPI v1.5.0 Specification and Reference Implementation is now available.
mAPI v1.5.0 is a recommended upgrade from mAPI v1.4.0.
Dependency
mAPI v1.5.0 not using DSNT, or using IPv4 for DSNT requires BSV Node v1.0.10.
mAPI v1.5.0 using IPv6 for DSNT requires BSV Node v1.0.13.
mAPI Specification
Specification: https://github.com/bitcoin-sv-specs/brfc-merchantapi
Features
mAPI v1.5.0 has an extensive list of changes from previous versions.
Improved Resilience
This release of the mAPI specification and reference implementation improves resilience against adversities.
If mAPI accepts transactions which are subsequently lost from node's Mempool (for whatever reason), mAPI automatically resubmits the transactions.
Standardised Errors
If the mAPI user gets a HTTP code 4xx response to submit transaction, they should attempt to fix the user error before resubmitting the transaction.
If the mAPI user gets a HTTP code 5xx response to submit transaction, they can resubmit the transaction after waiting for the issue at the server end to become resolved.
In addition, a new field 'FailureRetryable' in the submit transaction response indicates whether the user is able to resubmit the transaction, which relives the user from having to parse the detailed submission response. This field is particularly useful when submitting multiple transactions as response results may be mixed.
If the user resubmits a transaction with the same parameters, which has already been responded to, and is within the CLEAN_UP_TX_AFTER_DAYS and CLEAN_UP_TX_AFTER_MEMPOOL_EXPIRED_DAYS configuration settings, mAPI will return the original response again (idempotence).
If the mAPI user submits a transaction which is already on the blockchain but unknown to mAPI, mAPI will trigger a callback if specified.
If mAPI is configured to communicate with multiple nodes, any mixed results are mapped to the best result for the user.
Additional Operations
If mAPI identifies missing inputs in a transaction which it has stored, mAPI may be configured to resubmit the missing input transactions before the new transaction with the intention of reducing unsuccessful submissions.
Query transactions optionally returns the Merkle proof for a transaction.
A new endpoint, query transaction outputs is provided to obtain information about transaction outputs.
Additional validation is performed on transactions submitted which specify DSNT outputs.
DSNT outputs may specify the use of IPv6 for communication.
For further details about DSNT, please refer to https://github.com/bitcoin-sv-specs/protocol/blob/master/updates/double-spend-notifications.md
mAPI Reference Implementation
Binaries and source code with config files: https://github.com/bitcoin-sv/merchantapi-reference
Binaries: https://hub.docker.com/r/bitcoinsv/mapi
Additional Operations
mAPI administrators may control the list of unconfirmed transactions maintained for authenticated users, with new endpoints.
mAPI administrators may see the state of submitted transactions, Node's ZMQ and mAPI's block parser.
mAPI administrators may monitor mAPIs operation using Prometheus and Grafana.
Extended Configuration
There are more configurable timeouts and options in this version.
In this version, the default behaviour has been changed from logging transactions to not doing so.
This can be managed using the LOG_LEVEL_DEFAULT configuration option.
Bug Fixes
Several features have been added and bugs have been fixed.
Features and Bugs
- Additional validation of transactions using DSNT
- Aggregate different error messages from multiple nodes
- Add block parser status endpoint
- Resubmitting same transaction gets same response
- Improve Resilience
- Callback IP addresses support IPv6
- Improve logging info
- Emit Grafana output
- Standardize errors
- Resubmit a transaction's missing inputs
- Performance resilience changes
- Add Merkle proof to query transaction response
- Emit warning for incompatible bitcoind configuration settings
- Return HTTP 500 if node is unavailable
- Make REST responses consistent
- Add gettxouts endpoint
- Manage idempotent transactions
- Add failureRetryable to transaction responses