From e4e15b355ec7801438a1eaccdcc0bc8e13e9dfdd Mon Sep 17 00:00:00 2001 From: cyber-pc <165458555+cyber-pc@users.noreply.github.com> Date: Thu, 12 Mar 2026 10:23:56 +0700 Subject: [PATCH 01/15] Revert "Add OLD_QVAULT toggle" This reverts commit a17586b1aa9a7ac445acde392bea4ec12cbe7b66. --- src/Qubic.vcxproj | 1 - src/Qubic.vcxproj.filters | 8 +- src/contract_core/contract_def.h | 4 - src/contracts/QVAULT_old.h | 677 ------------------------------- src/qubic.cpp | 1 - 5 files changed, 4 insertions(+), 687 deletions(-) delete mode 100644 src/contracts/QVAULT_old.h diff --git a/src/Qubic.vcxproj b/src/Qubic.vcxproj index c09ed1a0b..c7a4f2f45 100644 --- a/src/Qubic.vcxproj +++ b/src/Qubic.vcxproj @@ -26,7 +26,6 @@ - diff --git a/src/Qubic.vcxproj.filters b/src/Qubic.vcxproj.filters index 6bff789b4..e5184e84c 100644 --- a/src/Qubic.vcxproj.filters +++ b/src/Qubic.vcxproj.filters @@ -362,12 +362,12 @@ contracts + + contracts + oracle_core - - contracts - @@ -418,4 +418,4 @@ platform - \ No newline at end of file + diff --git a/src/contract_core/contract_def.h b/src/contract_core/contract_def.h index 035e2b23f..a0e8ff8d8 100644 --- a/src/contract_core/contract_def.h +++ b/src/contract_core/contract_def.h @@ -112,11 +112,7 @@ #define CONTRACT_INDEX QVAULT_CONTRACT_INDEX #define CONTRACT_STATE_TYPE QVAULT #define CONTRACT_STATE2_TYPE QVAULT2 -#ifdef OLD_QVAULT -#include "contracts/QVAULT_old.h" -#else #include "contracts/QVAULT.h" -#endif #undef CONTRACT_INDEX #undef CONTRACT_STATE_TYPE diff --git a/src/contracts/QVAULT_old.h b/src/contracts/QVAULT_old.h deleted file mode 100644 index 9142d275d..000000000 --- a/src/contracts/QVAULT_old.h +++ /dev/null @@ -1,677 +0,0 @@ -using namespace QPI; - -constexpr uint64 QVAULT_MAX_REINVEST_AMOUNT = 100000000000ULL; -constexpr uint64 QVAULT_QCAP_ASSETNAME = 1346454353; -constexpr uint64 QVAULT_QCAP_MAX_SUPPLY = 21000000; -constexpr uint32 QVAULT_MAX_NUMBER_OF_BANNED_ADDRESSES = 16; - -struct QVAULT2 -{ -}; - -struct QVAULT : public ContractBase -{ - struct StateData - { - id QCAP_ISSUER; - id authAddress1, authAddress2, authAddress3, newAuthAddress1, newAuthAddress2, newAuthAddress3; - id reinvestingAddress, newReinvestingAddress1, newReinvestingAddress2, newReinvestingAddress3; - id adminAddress, newAdminAddress1, newAdminAddress2, newAdminAddress3; - id bannedAddress1, bannedAddress2, bannedAddress3; - id unbannedAddress1, unbannedAddress2, unbannedAddress3; - Array bannedAddress; - uint32 numberOfBannedAddress; - uint32 shareholderDividend, QCAPHolderPermille, reinvestingPermille, devPermille, burnPermille; - uint32 newQCAPHolderPermille1, newReinvestingPermille1, newDevPermille1; - uint32 newQCAPHolderPermille2, newReinvestingPermille2, newDevPermille2; - uint32 newQCAPHolderPermille3, newReinvestingPermille3, newDevPermille3; - }; - -public: - - /* - submitAuthAddress PROCEDURE - multisig addresses can submit the new multisig address in this procedure. - */ - - struct submitAuthAddress_input - { - id newAddress; - }; - - struct submitAuthAddress_output - { - }; - - /* - changeAuthAddress PROCEDURE - the new multisig address can be changed by multisig address in this procedure. - the new multisig address should be submitted by the 2 multisig addresses in submitAuthAddress. if else, it will not be changed with new address - */ - - struct changeAuthAddress_input - { - uint32 numberOfChangedAddress; - }; - - struct changeAuthAddress_output - { - }; - - /* - submitDistributionPermille PROCEDURE - the new distribution Permilles can be submitted by the multisig addresses in this procedure. - */ - - struct submitDistributionPermille_input - { - uint32 newQCAPHolderPermille; - uint32 newReinvestingPermille; - uint32 newDevPermille; - }; - - struct submitDistributionPermille_output - { - }; - - /* - changeDistributionPermille PROCEDURE - the new distribution Permilles can be changed by multisig address in this procedure. - the new distribution Permilles should be submitted by multsig addresses in submitDistributionPermille PROCEDURE. if else, it will not be changed with new Permilles. - */ - - struct changeDistributionPermille_input - { - uint32 newQCAPHolderPermille; - uint32 newReinvestingPermille; - uint32 newDevPermille; - }; - - struct changeDistributionPermille_output - { - }; - - /* - submitReinvestingAddress PROCEDURE - the new reinvestingAddress can be submitted by the multisig addresses in this procedure. - */ - - struct submitReinvestingAddress_input - { - id newAddress; - }; - - struct submitReinvestingAddress_output - { - }; - - /* - changeReinvestingAddress PROCEDURE - the new reinvesting address can be changed by multisig address in this procedure. - the new reinvesting address should be submitted by multsig addresses in submitReinvestingAddress. if else, it will not be changed with new address. - */ - - struct changeReinvestingAddress_input - { - id newAddress; - }; - - struct changeReinvestingAddress_output - { - - }; - - struct getData_input - { - }; - - struct getData_output - { - uint64 numberOfBannedAddress; - uint32 shareholderDividend, QCAPHolderPermille, reinvestingPermille, devPermille; - id authAddress1, authAddress2, authAddress3, reinvestingAddress, adminAddress; - id newAuthAddress1, newAuthAddress2, newAuthAddress3; - id newReinvestingAddress1, newReinvestingAddress2, newReinvestingAddress3; - id newAdminAddress1, newAdminAddress2, newAdminAddress3; - id bannedAddress1, bannedAddress2, bannedAddress3; - id unbannedAddress1, unbannedAddress2, unbannedAddress3; - }; - - /* - submitAdminAddress PROCEDURE - the new adminAddress can be submitted by the multisig addresses in this procedure. - */ - - struct submitAdminAddress_input - { - id newAddress; - }; - - struct submitAdminAddress_output - { - }; - - /* - changeAdminAddress PROCEDURE - the new admin address can be changed by multisig address in this procedure. - the new admin address should be submitted by multsig addresses in submitAdminAddress PROCEDURE. if else, it will not be changed with new address. - */ - - struct changeAdminAddress_input - { - id newAddress; - }; - - struct changeAdminAddress_output - { - }; - - /* - submitBannedAddress PROCEDURE - the banned addresses can be submitted by multisig address in this procedure. - */ - struct submitBannedAddress_input - { - id bannedAddress; - }; - - struct submitBannedAddress_output - { - }; - - /* - saveBannedAddress PROCEDURE - the banned address can be changed by multisig address in this procedure. - the banned address should be submitted by multisig addresses in submitBannedAddress PROCEDURE. if else, it will not be saved. - */ - - struct saveBannedAddress_input - { - id bannedAddress; - }; - - struct saveBannedAddress_output - { - }; - - /* - submitUnbannedAddress PROCEDURE - the unbanned addresses can be submitted by multisig address in this procedure. - */ - - struct submitUnbannedAddress_input - { - id unbannedAddress; - }; - - struct submitUnbannedAddress_output - { - }; - - /* - unblockBannedAddress PROCEDURE - the banned address can be unblocked by multisig address in this procedure. - the unbanned address should be submitted by multisig addresses in submitUnbannedAddress PROCEDURE. if else, it will not be unblocked. - */ - - struct unblockBannedAddress_input - { - id unbannedAddress; - }; - - struct unblockBannedAddress_output - { - }; - -protected: - - PUBLIC_PROCEDURE(submitAuthAddress) - { - if(qpi.invocator() == state.get().authAddress1) - { - state.mut().newAuthAddress1 = input.newAddress; - } - if(qpi.invocator() == state.get().authAddress2) - { - state.mut().newAuthAddress2 = input.newAddress; - } - if(qpi.invocator() == state.get().authAddress3) - { - state.mut().newAuthAddress3 = input.newAddress; - } - - } - - struct changeAuthAddress_locals { - bit succeed; - }; - - PUBLIC_PROCEDURE_WITH_LOCALS(changeAuthAddress) - { - if(qpi.invocator() != state.get().authAddress1 && qpi.invocator() != state.get().authAddress2 && qpi.invocator() != state.get().authAddress3) - { - return ; - } - - locals.succeed = 0; - - if(qpi.invocator() != state.get().authAddress1 && input.numberOfChangedAddress == 1 && state.get().newAuthAddress2 != NULL_ID && state.get().newAuthAddress2 == state.get().newAuthAddress3) - { - state.mut().authAddress1 = state.get().newAuthAddress2; - locals.succeed = 1; - } - - if(qpi.invocator() != state.get().authAddress2 && input.numberOfChangedAddress == 2 && state.get().newAuthAddress1 != NULL_ID && state.get().newAuthAddress1 == state.get().newAuthAddress3) - { - state.mut().authAddress2 = state.get().newAuthAddress1; - locals.succeed = 1; - } - - if(qpi.invocator() != state.get().authAddress3 && input.numberOfChangedAddress == 3 && state.get().newAuthAddress1 != NULL_ID && state.get().newAuthAddress1 == state.get().newAuthAddress2) - { - state.mut().authAddress3 = state.get().newAuthAddress1; - locals.succeed = 1; - } - - if(locals.succeed == 1) - { - state.mut().newAuthAddress1 = NULL_ID; - state.mut().newAuthAddress2 = NULL_ID; - state.mut().newAuthAddress3 = NULL_ID; - } - } - - PUBLIC_PROCEDURE(submitDistributionPermille) - { - if(input.newDevPermille + input.newQCAPHolderPermille + input.newReinvestingPermille + state.get().shareholderDividend + state.get().burnPermille != 1000) - { - return ; - } - - if(qpi.invocator() == state.get().authAddress1) - { - state.mut().newDevPermille1 = input.newDevPermille; - state.mut().newQCAPHolderPermille1 = input.newQCAPHolderPermille; - state.mut().newReinvestingPermille1 = input.newReinvestingPermille; - } - - if(qpi.invocator() == state.get().authAddress2) - { - state.mut().newDevPermille2 = input.newDevPermille; - state.mut().newQCAPHolderPermille2 = input.newQCAPHolderPermille; - state.mut().newReinvestingPermille2 = input.newReinvestingPermille; - } - - if(qpi.invocator() == state.get().authAddress3) - { - state.mut().newDevPermille3 = input.newDevPermille; - state.mut().newQCAPHolderPermille3 = input.newQCAPHolderPermille; - state.mut().newReinvestingPermille3 = input.newReinvestingPermille; - } - - } - - PUBLIC_PROCEDURE(changeDistributionPermille) - { - if(qpi.invocator() != state.get().authAddress1 && qpi.invocator() != state.get().authAddress2 && qpi.invocator() != state.get().authAddress3) - { - return ; - } - - if(input.newDevPermille + input.newQCAPHolderPermille + input.newReinvestingPermille + state.get().shareholderDividend + state.get().burnPermille != 1000) - { - return ; - } - - if(input.newDevPermille == 0 || input.newDevPermille != state.get().newDevPermille1 || state.get().newDevPermille1 != state.get().newDevPermille2 || state.get().newDevPermille2 != state.get().newDevPermille3) - { - return ; - } - - if(input.newQCAPHolderPermille == 0 || input.newQCAPHolderPermille != state.get().newQCAPHolderPermille1 || state.get().newQCAPHolderPermille1 != state.get().newQCAPHolderPermille2 || state.get().newQCAPHolderPermille2 != state.get().newQCAPHolderPermille3) - { - return ; - } - - if(input.newReinvestingPermille == 0 || input.newReinvestingPermille != state.get().newReinvestingPermille1 || state.get().newReinvestingPermille1 != state.get().newReinvestingPermille2 || state.get().newReinvestingPermille2 != state.get().newReinvestingPermille3) - { - return ; - } - - state.mut().devPermille = state.get().newDevPermille1; - state.mut().QCAPHolderPermille = state.get().newQCAPHolderPermille1; - state.mut().reinvestingPermille = state.get().newReinvestingPermille1; - - state.mut().newDevPermille1 = 0; - state.mut().newDevPermille2 = 0; - state.mut().newDevPermille3 = 0; - - state.mut().newQCAPHolderPermille1 = 0; - state.mut().newQCAPHolderPermille2 = 0; - state.mut().newQCAPHolderPermille3 = 0; - - state.mut().newReinvestingPermille1 = 0; - state.mut().newReinvestingPermille2 = 0; - state.mut().newReinvestingPermille3 = 0; - } - - PUBLIC_PROCEDURE(submitReinvestingAddress) - { - if(qpi.invocator() == state.get().authAddress1) - { - state.mut().newReinvestingAddress1 = input.newAddress; - } - if(qpi.invocator() == state.get().authAddress2) - { - state.mut().newReinvestingAddress2 = input.newAddress; - } - if(qpi.invocator() == state.get().authAddress3) - { - state.mut().newReinvestingAddress3 = input.newAddress; - } - } - - PUBLIC_PROCEDURE(changeReinvestingAddress) - { - if(qpi.invocator() != state.get().authAddress1 && qpi.invocator() != state.get().authAddress2 && qpi.invocator() != state.get().authAddress3) - { - return ; - } - - if(input.newAddress == NULL_ID || input.newAddress != state.get().newReinvestingAddress1 || state.get().newReinvestingAddress1 != state.get().newReinvestingAddress2 || state.get().newReinvestingAddress2 != state.get().newReinvestingAddress3) - { - return ; - } - - state.mut().reinvestingAddress = state.get().newReinvestingAddress1; - - state.mut().newReinvestingAddress1 = NULL_ID; - state.mut().newReinvestingAddress2 = NULL_ID; - state.mut().newReinvestingAddress3 = NULL_ID; - } - - PUBLIC_FUNCTION(getData) - { - output.authAddress1 = state.get().authAddress1; - output.authAddress2 = state.get().authAddress2; - output.authAddress3 = state.get().authAddress3; - output.reinvestingAddress = state.get().reinvestingAddress; - output.shareholderDividend = state.get().shareholderDividend; - output.devPermille = state.get().devPermille; - output.QCAPHolderPermille = state.get().QCAPHolderPermille; - output.reinvestingPermille = state.get().reinvestingPermille; - output.adminAddress = state.get().adminAddress; - output.newAuthAddress1 = state.get().newAuthAddress1; - output.newAuthAddress2 = state.get().newAuthAddress2; - output.newAuthAddress3 = state.get().newAuthAddress3; - output.newAdminAddress1 = state.get().newAdminAddress1; - output.newAdminAddress2 = state.get().newAdminAddress2; - output.newAdminAddress3 = state.get().newAdminAddress3; - output.newReinvestingAddress1 = state.get().newReinvestingAddress1; - output.newReinvestingAddress2 = state.get().newReinvestingAddress2; - output.newReinvestingAddress3 = state.get().newReinvestingAddress3; - output.numberOfBannedAddress = state.get().numberOfBannedAddress; - output.bannedAddress1 = state.get().bannedAddress1; - output.bannedAddress2 = state.get().bannedAddress2; - output.bannedAddress3 = state.get().bannedAddress3; - output.unbannedAddress1 = state.get().unbannedAddress1; - output.unbannedAddress2 = state.get().unbannedAddress2; - output.unbannedAddress3 = state.get().unbannedAddress3; - - } - - PUBLIC_PROCEDURE(submitAdminAddress) - { - if(qpi.invocator() == state.get().authAddress1) - { - state.mut().newAdminAddress1 = input.newAddress; - } - if(qpi.invocator() == state.get().authAddress2) - { - state.mut().newAdminAddress2 = input.newAddress; - } - if(qpi.invocator() == state.get().authAddress3) - { - state.mut().newAdminAddress3 = input.newAddress; - } - - } - - PUBLIC_PROCEDURE(changeAdminAddress) - { - if(qpi.invocator() != state.get().authAddress1 && qpi.invocator() != state.get().authAddress2 && qpi.invocator() != state.get().authAddress3) - { - return ; - } - - if(input.newAddress == NULL_ID || input.newAddress != state.get().newAdminAddress1 || state.get().newAdminAddress1 != state.get().newAdminAddress2 || state.get().newAdminAddress2 != state.get().newAdminAddress3) - { - return ; - } - - state.mut().adminAddress = state.get().newAdminAddress1; - - state.mut().newAdminAddress1 = NULL_ID; - state.mut().newAdminAddress2 = NULL_ID; - state.mut().newAdminAddress3 = NULL_ID; - } - - - PUBLIC_PROCEDURE(submitBannedAddress) - { - if(qpi.invocator() == state.get().authAddress1) - { - state.mut().bannedAddress1 = input.bannedAddress; - } - if(qpi.invocator() == state.get().authAddress2) - { - state.mut().bannedAddress2 = input.bannedAddress; - } - if(qpi.invocator() == state.get().authAddress3) - { - state.mut().bannedAddress3 = input.bannedAddress; - } - - } - - PUBLIC_PROCEDURE(saveBannedAddress) - { - if(state.get().numberOfBannedAddress >= QVAULT_MAX_NUMBER_OF_BANNED_ADDRESSES) - { - return ; - } - - if(qpi.invocator() != state.get().authAddress1 && qpi.invocator() != state.get().authAddress2 && qpi.invocator() != state.get().authAddress3) - { - return ; - } - - if(input.bannedAddress == NULL_ID || input.bannedAddress != state.get().bannedAddress1 || state.get().bannedAddress1 != state.get().bannedAddress2 || state.get().bannedAddress2 != state.get().bannedAddress3) - { - return ; - } - - state.mut().bannedAddress.set(state.get().numberOfBannedAddress, input.bannedAddress); - - state.mut().numberOfBannedAddress++; - state.mut().newAdminAddress1 = NULL_ID; - state.mut().newAdminAddress2 = NULL_ID; - state.mut().newAdminAddress3 = NULL_ID; - - } - - PUBLIC_PROCEDURE(submitUnbannedAddress) - { - if(qpi.invocator() == state.get().authAddress1) - { - state.mut().unbannedAddress1 = input.unbannedAddress; - } - if(qpi.invocator() == state.get().authAddress2) - { - state.mut().unbannedAddress2 = input.unbannedAddress; - } - if(qpi.invocator() == state.get().authAddress3) - { - state.mut().unbannedAddress3 = input.unbannedAddress; - } - - } - - struct unblockBannedAddress_locals - { - uint32 _t, flag; - }; - - PUBLIC_PROCEDURE_WITH_LOCALS(unblockBannedAddress) - { - if(qpi.invocator() != state.get().authAddress1 && qpi.invocator() != state.get().authAddress2 && qpi.invocator() != state.get().authAddress3) - { - return ; - } - - if(input.unbannedAddress == NULL_ID || input.unbannedAddress != state.get().unbannedAddress1 || state.get().unbannedAddress1 != state.get().unbannedAddress2 || state.get().unbannedAddress2 != state.get().unbannedAddress3) - { - return ; - } - - locals.flag = 0; - - for(locals._t = 0; locals._t < state.get().numberOfBannedAddress; locals._t++) - { - if(locals.flag == 1 || input.unbannedAddress == state.get().bannedAddress.get(locals._t)) - { - if(locals._t == state.get().numberOfBannedAddress - 1) - { - state.mut().bannedAddress.set(locals._t, NULL_ID); - locals.flag = 1; - break; - } - state.mut().bannedAddress.set(locals._t, state.get().bannedAddress.get(locals._t + 1)); - locals.flag = 1; - } - } - - if(locals.flag == 1) - { - state.mut().numberOfBannedAddress--; - } - state.mut().unbannedAddress1 = NULL_ID; - state.mut().unbannedAddress2 = NULL_ID; - state.mut().unbannedAddress3 = NULL_ID; - - } - - REGISTER_USER_FUNCTIONS_AND_PROCEDURES() - { - REGISTER_USER_FUNCTION(getData, 1); - - REGISTER_USER_PROCEDURE(submitAuthAddress, 1); - REGISTER_USER_PROCEDURE(changeAuthAddress, 2); - REGISTER_USER_PROCEDURE(submitDistributionPermille, 3); - REGISTER_USER_PROCEDURE(changeDistributionPermille, 4); - REGISTER_USER_PROCEDURE(submitReinvestingAddress, 5); - REGISTER_USER_PROCEDURE(changeReinvestingAddress, 6); - REGISTER_USER_PROCEDURE(submitAdminAddress, 7); - REGISTER_USER_PROCEDURE(changeAdminAddress, 8); - REGISTER_USER_PROCEDURE(submitBannedAddress, 9); - REGISTER_USER_PROCEDURE(saveBannedAddress, 10); - REGISTER_USER_PROCEDURE(submitUnbannedAddress, 11); - REGISTER_USER_PROCEDURE(unblockBannedAddress, 12); - - } - - INITIALIZE() - { - state.mut().QCAP_ISSUER = ID(_Q, _C, _A, _P, _W, _M, _Y, _R, _S, _H, _L, _B, _J, _H, _S, _T, _T, _Z, _Q, _V, _C, _I, _B, _A, _R, _V, _O, _A, _S, _K, _D, _E, _N, _A, _S, _A, _K, _N, _O, _B, _R, _G, _P, _F, _W, _W, _K, _R, _C, _U, _V, _U, _A, _X, _Y, _E); - state.mut().authAddress1 = ID(_T, _K, _U, _W, _W, _S, _N, _B, _A, _E, _G, _W, _J, _H, _Q, _J, _D, _F, _L, _G, _Q, _H, _J, _J, _C, _J, _B, _A, _X, _B, _S, _Q, _M, _Q, _A, _Z, _J, _J, _D, _Y, _X, _E, _P, _B, _V, _B, _B, _L, _I, _Q, _A, _N, _J, _T, _I, _D); - state.mut().authAddress2 = ID(_F, _X, _J, _F, _B, _T, _J, _M, _Y, _F, _J, _H, _P, _B, _X, _C, _D, _Q, _T, _L, _Y, _U, _K, _G, _M, _H, _B, _B, _Z, _A, _A, _F, _T, _I, _C, _W, _U, _K, _R, _B, _M, _E, _K, _Y, _N, _U, _P, _M, _R, _M, _B, _D, _N, _D, _R, _G); - state.mut().authAddress3 = ID(_K, _E, _F, _D, _Z, _T, _Y, _L, _F, _E, _R, _A, _H, _D, _V, _L, _N, _Q, _O, _R, _D, _H, _F, _Q, _I, _B, _S, _B, _Z, _C, _W, _S, _Z, _X, _Z, _F, _F, _A, _N, _O, _T, _F, _A, _H, _W, _M, _O, _V, _G, _T, _R, _Q, _J, _P, _X, _D); - state.mut().reinvestingAddress = ID(_R, _U, _U, _Y, _R, _V, _N, _K, _J, _X, _M, _L, _R, _B, _B, _I, _R, _I, _P, _D, _I, _B, _M, _H, _D, _H, _U, _A, _Z, _B, _Q, _K, _N, _B, _J, _T, _R, _D, _S, _P, _G, _C, _L, _Z, _C, _Q, _W, _A, _K, _C, _F, _Q, _J, _K, _K, _E); - state.mut().adminAddress = ID(_H, _E, _C, _G, _U, _G, _H, _C, _J, _K, _Q, _O, _S, _D, _T, _M, _E, _H, _Q, _Y, _W, _D, _D, _T, _L, _F, _D, _A, _S, _Z, _K, _M, _G, _J, _L, _S, _R, _C, _S, _T, _H, _H, _A, _P, _P, _E, _D, _L, _G, _B, _L, _X, _J, _M, _N, _D); - - state.mut().shareholderDividend = 30; - state.mut().QCAPHolderPermille = 500; - state.mut().reinvestingPermille = 450; - state.mut().devPermille = 20; - state.mut().burnPermille = 0; - - /* - initial banned addresses - */ - state.mut().bannedAddress.set(0, ID(_K, _E, _F, _D, _Z, _T, _Y, _L, _F, _E, _R, _A, _H, _D, _V, _L, _N, _Q, _O, _R, _D, _H, _F, _Q, _I, _B, _S, _B, _Z, _C, _W, _S, _Z, _X, _Z, _F, _F, _A, _N, _O, _T, _F, _A, _H, _W, _M, _O, _V, _G, _T, _R, _Q, _J, _P, _X, _D)); - state.mut().bannedAddress.set(1, ID(_E, _S, _C, _R, _O, _W, _B, _O, _T, _F, _T, _F, _I, _C, _I, _F, _P, _U, _X, _O, _J, _K, _G, _Q, _P, _Y, _X, _C, _A, _B, _L, _Z, _V, _M, _M, _U, _C, _M, _J, _F, _S, _G, _S, _A, _I, _A, _T, _Y, _I, _N, _V, _T, _Y, _G, _O, _A)); - state.mut().numberOfBannedAddress = 2; - - } - - struct END_EPOCH_locals - { - Entity entity; - AssetPossessionIterator iter; - Asset QCAPId; - uint64 revenue; - uint64 paymentForShareholders; - uint64 paymentForQCAPHolders; - uint64 paymentForReinvest; - uint64 paymentForDevelopment; - uint64 amountOfBurn; - uint64 circulatedSupply; - uint32 _t; - id possessorPubkey; - }; - - END_EPOCH_WITH_LOCALS() - { - qpi.getEntity(SELF, locals.entity); - locals.revenue = locals.entity.incomingAmount - locals.entity.outgoingAmount; - - locals.paymentForShareholders = div(locals.revenue * state.get().shareholderDividend, 1000ULL); - locals.paymentForQCAPHolders = div(locals.revenue * state.get().QCAPHolderPermille, 1000ULL); - locals.paymentForReinvest = div(locals.revenue * state.get().reinvestingPermille, 1000ULL); - locals.amountOfBurn = div(locals.revenue * state.get().burnPermille, 1000ULL); - locals.paymentForDevelopment = locals.revenue - locals.paymentForShareholders - locals.paymentForQCAPHolders - locals.paymentForReinvest - locals.amountOfBurn; - - if(locals.paymentForReinvest > QVAULT_MAX_REINVEST_AMOUNT) - { - locals.paymentForQCAPHolders += locals.paymentForReinvest - QVAULT_MAX_REINVEST_AMOUNT; - locals.paymentForReinvest = QVAULT_MAX_REINVEST_AMOUNT; - } - - qpi.distributeDividends(div(locals.paymentForShareholders, 676ULL)); - qpi.transfer(state.get().adminAddress, locals.paymentForDevelopment); - qpi.transfer(state.get().reinvestingAddress, locals.paymentForReinvest); - qpi.burn(locals.amountOfBurn); - - locals.circulatedSupply = QVAULT_QCAP_MAX_SUPPLY; - - for(locals._t = 0 ; locals._t < state.get().numberOfBannedAddress; locals._t++) - { - locals.circulatedSupply -= qpi.numberOfPossessedShares(QVAULT_QCAP_ASSETNAME, state.get().QCAP_ISSUER, state.get().bannedAddress.get(locals._t), state.get().bannedAddress.get(locals._t), QX_CONTRACT_INDEX, QX_CONTRACT_INDEX); - } - - locals.QCAPId.assetName = QVAULT_QCAP_ASSETNAME; - locals.QCAPId.issuer = state.get().QCAP_ISSUER; - - locals.iter.begin(locals.QCAPId); - while (!locals.iter.reachedEnd()) - { - locals.possessorPubkey = locals.iter.possessor(); - - for(locals._t = 0 ; locals._t < state.get().numberOfBannedAddress; locals._t++) - { - if(locals.possessorPubkey == state.get().bannedAddress.get(locals._t)) - { - break; - } - } - - if(locals._t == state.get().numberOfBannedAddress) - { - qpi.transfer(locals.possessorPubkey, div(locals.paymentForQCAPHolders, locals.circulatedSupply) * qpi.numberOfPossessedShares(QVAULT_QCAP_ASSETNAME, state.get().QCAP_ISSUER, locals.possessorPubkey, locals.possessorPubkey, QX_CONTRACT_INDEX, QX_CONTRACT_INDEX)); - } - - locals.iter.next(); - } - - } -}; diff --git a/src/qubic.cpp b/src/qubic.cpp index 4e3e04f40..8e20e3597 100644 --- a/src/qubic.cpp +++ b/src/qubic.cpp @@ -1,5 +1,4 @@ #define SINGLE_COMPILE_UNIT -// #define OLD_QVAULT //#define INCLUDE_CONTRACT_TEST_EXAMPLES From 3f541def972e0b50bd1997817c078268eaed8738 Mon Sep 17 00:00:00 2001 From: cyber-pc <165458555+cyber-pc@users.noreply.github.com> Date: Thu, 12 Mar 2026 10:31:12 +0700 Subject: [PATCH 02/15] Remove unused SupplyWatcher_old.h in project filter. --- src/Qubic.vcxproj.filters | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/Qubic.vcxproj.filters b/src/Qubic.vcxproj.filters index e5184e84c..24b11e9e1 100644 --- a/src/Qubic.vcxproj.filters +++ b/src/Qubic.vcxproj.filters @@ -362,9 +362,6 @@ contracts - - contracts - oracle_core From 27dd2a76d52f4faa72e98ba1c3075c3c84513be0 Mon Sep 17 00:00:00 2001 From: fnordspace Date: Thu, 12 Mar 2026 14:17:46 +0100 Subject: [PATCH 03/15] Fix preprocessor guard for loading execution fee files on non-scratch restart (#793) Changed #ifndef to #if ! so that loadContractExecFeeFiles() is called when START_NETWORK_FROM_SCRATCH is 0 (node joining existing network). The #ifndef check always skipped loading because the macro is always defined, causing misalignment after epoch transition. --- src/qubic.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/qubic.cpp b/src/qubic.cpp index 8e20e3597..402be3668 100644 --- a/src/qubic.cpp +++ b/src/qubic.cpp @@ -6118,7 +6118,7 @@ static bool initialize() } if (!loadContractStateFiles()) return false; -#ifndef START_NETWORK_FROM_SCRATCH +#if !START_NETWORK_FROM_SCRATCH if (!loadContractExecFeeFiles()) return false; #endif From 283771dc3f054ca0059e43ce6e1cb5bfa57b34c5 Mon Sep 17 00:00:00 2001 From: Franziska Mueller <11660876+Franziska-Mueller@users.noreply.github.com> Date: Fri, 13 Mar 2026 11:14:42 +0100 Subject: [PATCH 04/15] Update contract verify action to version 1.0.5 The new release of contract-verify checks that contracts do not define direct member variables in the contract struct. They all need to be defined in the nested StateData struct. --- .github/workflows/contract-verify.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/contract-verify.yml b/.github/workflows/contract-verify.yml index 19b325637..33f9a173f 100644 --- a/.github/workflows/contract-verify.yml +++ b/.github/workflows/contract-verify.yml @@ -39,6 +39,6 @@ jobs: echo "contract-filepaths=$files" >> "$GITHUB_OUTPUT" - name: Contract verify action step id: verify - uses: Franziska-Mueller/qubic-contract-verify@v1.0.4 + uses: Franziska-Mueller/qubic-contract-verify@v1.0.5 with: filepaths: '${{ steps.filepaths.outputs.contract-filepaths }}' From 6529e4467f0efe8f158e2c50674b6ebd56408a58 Mon Sep 17 00:00:00 2001 From: Sergi Mias Martinez <25818384+sergimima@users.noreply.github.com> Date: Mon, 16 Mar 2026 15:17:44 +0100 Subject: [PATCH 05/15] Vottun Bridge * Add VottunBridge smart contract for cross-chain bridge functionality * Compilation fixes * Fixed compilation errors * Update VottunBridge.h * Compilation working * feat: Add VottunBridge smart contract with comprehensive test suite - Implement bidirectional bridge between Qubic and Ethereum - Add 27 comprehensive tests covering core functionality - Support for order management, admin functions, and fee handling - Include input validation and error handling - Ready for deployment and IPO process * Address reviewer feedback: clean up comments, optimize functions, fix division operators - Remove duplicate and Spanish comments from VottunBridge.h - Clean up 'NEW'/'NUEVA' comments throughout the code - Optimize isAdmin and isManager functions (remove unnecessary locals structs) - Replace division operators with div() function for fee calculations - Add build artifacts to .gitignore - Fix syntax errors and improve code consistency * Address additional reviewer feedback: optimize getAdminID function and clean up build artifacts - Remove empty getAdminID_locals struct and use PUBLIC_FUNCTION macro - Remove versioned build/test artifacts from repository - Clean up remaining comments and code optimizations - Fix division operators to use div() function consistently * Fix isManager function: use WITH_LOCALS for loop variable - Refactor isManager to use PRIVATE_FUNCTION_WITH_LOCALS - Move loop variable 'i' to isManager_locals struct - Comply with Qubic rule: no local variables allowed in functions - Address Franziska's feedback on loop variable requirements * Fix VottunBridge refund security vulnerability KS-VB-F-01 - Add tokensReceived and tokensLocked flags to BridgeOrder struct - Update transferToContract to accept orderId and set per-order flags - Modify refundOrder to check tokensReceived/tokensLocked before refund - Update completeOrder to verify token flags for consistency - Add comprehensive security tests validating the fix - Prevent exploit where users could refund tokens they never deposited Tests added: - SecurityRefundValidation: Validates new token tracking flags - ExploitPreventionTest: Confirms original vulnerability is blocked - TransferFlowValidation: Tests complete transfer flow security - StateConsistencyTests: Verifies state counter consistency All 24 tests pass successfully. * Fix code style formatting for security tests - Update TEST_F declarations to use braces on new lines - Fix struct declarations formatting - Fix if statement brace formatting - Comply with project code style guidelines * Fix VottunBridge code style and PR review issues - Remove all 'NEW' comments from functions and procedures - Fix char literal '\0' to numeric 0 in EthBridgeLogger - Keep underscore variables (_tradeFeeBillionths, _earnedFees, etc.) as they follow Qubic standard pattern - All opening braces { are now on new lines per Qubic style guidelines * Removed coment * last fix * Fixed order in createOrder_input * update * fix for testnet * admin addresess update * update on addresses * update in admins * update in proposals arry * update * epoch update * sc update * update in order status return * Refactor fee accumulation and order handling in VottunBridge. Fees are now accumulated only after successful order creation and refunds include both the order amount and fees. Improved slot management for proposals and added checks for multisig admin verification. * update for compiler * Refactor VottunBridge error handling to use enumerated error codes for insufficient transaction fees. Update test cases to validate fee requirements and proposal management, ensuring proper state transitions and error responses. * Implement cancelProposal functionality in VottunBridge, allowing proposal creators to cancel their proposals. Update cleanup logic to handle both executed and inactive proposals. Adjust token locking mechanism to refund excess amounts sent by users. Register cancelProposal procedure in the contract. * Enhance VottunBridge contract by defining new contract index and state types. Implement setProposalById and cancelProposal methods in the testing framework. Update test cases to validate proposal management and token refund mechanisms. Adjust project configuration to include necessary directories for testing. * Refactor fee calculation and refund logic in VottunBridge to include underflow protection. Introduce separate variables for operator and network fees, ensuring only available fees are refunded. Update available fees calculations in multiple functions for consistency and safety. * Enhance VottunBridge contract by adding security checks to prevent duplicate admins and managers during proposal processing. Update logic to ensure that existing addresses are not replaced or added again, maintaining the integrity of the admin and manager lists. * Add VOTTUN contract to ContractDescription in contract_def.h * Update VOTTUN contract details in ContractDescription to reflect new proposal and IPO epochs * Update EPOCH definition in public_settings.h to reflect new startup configuration * Update EPOCH value in public_settings.h to 199 for node startup configuration * Refactor proposal management in VottunBridge contract to utilize a dedicated slot index for storing new proposals. This change improves clarity and ensures the correct slot is used when setting proposals, enhancing overall contract functionality. * Add manager count tracking in VottunBridge contract to enforce manager limit. Implement checks to prevent adding more than three managers during proposal processing, enhancing contract security and integrity. * Add reserved fees tracking in VottunBridge contract to manage pending orders. Implement logic to reserve and release fees for completed orders and refunds, enhancing fee management and underflow protection. * Update VottunBridge contract to improve order creation and refund processes. Introduce minimum order amount validation to prevent zero-fee spam, enhance fee management with invocation rewards, and implement single-pass recycling for order and proposal slots. Add new refund functionality and corresponding tests to ensure proper fee handling and order status updates. * Update feeRecipient and managers initialization in VottunBridge contract to enhance clarity and maintainability. Adjust admin addresses to reflect new configurations while ensuring proper initialization of state variables. * Remove unrelated files from PR: revert private_settings, public_settings, peers, qubic.cpp, packages.config, gitignore; remove cli.md and tests.md Made-with: Cursor * Update guideline for VottunBridge to state change detection * Update .gitignore to include new files and directories; modify contract definition for VottunBridge state; add contract_vottunbridge to project files. * Fix XML declaration in test.vcxproj.filters file * Remove out/ from repo, add to .gitignore Made-with: Cursor * Fix reviewer feedback: revert .gitignore to upstream, fix orphaned #endif in contract_def.h Made-with: Cursor * Refactor contract_def.h: Remove conditional compilation for PULSE contract definitions --- src/contract_core/contract_def.h | 12 + src/contracts/VottunBridge.h | 2097 ++++++++++++++++++++++++++++++ test/CMakeLists.txt | 1 + test/contract_vottunbridge.cpp | 916 +++++++++++++ test/test.vcxproj | 1 + test/test.vcxproj.filters | 1 + 6 files changed, 3028 insertions(+) create mode 100644 src/contracts/VottunBridge.h create mode 100644 test/contract_vottunbridge.cpp diff --git a/src/contract_core/contract_def.h b/src/contract_core/contract_def.h index a0e8ff8d8..550eb70fc 100644 --- a/src/contract_core/contract_def.h +++ b/src/contract_core/contract_def.h @@ -254,6 +254,16 @@ #define CONTRACT_STATE2_TYPE PULSE2 #include "contracts/Pulse.h" +#undef CONTRACT_INDEX +#undef CONTRACT_STATE_TYPE +#undef CONTRACT_STATE2_TYPE + +#define VOTTUNBRIDGE_CONTRACT_INDEX 25 +#define CONTRACT_INDEX VOTTUNBRIDGE_CONTRACT_INDEX +#define CONTRACT_STATE_TYPE VOTTUNBRIDGE +#define CONTRACT_STATE2_TYPE VOTTUNBRIDGE2 +#include "contracts/VottunBridge.h" + // new contracts should be added above this line #ifdef INCLUDE_CONTRACT_TEST_EXAMPLES @@ -364,6 +374,7 @@ constexpr struct ContractDescription {"QTF", 199, 10000, sizeof(QTF::StateData)}, // proposal in epoch 197, IPO in 198, construction and first use in 199 {"QDUEL", 199, 10000, sizeof(QDUEL::StateData)}, // proposal in epoch 197, IPO in 198, construction and first use in 199 {"PULSE", 204, 10000, sizeof(PULSE::StateData)}, // proposal in epoch 202, IPO in 203, construction and first use in 204 + {"VOTTUN", 205, 10000, sizeof(VOTTUNBRIDGE::StateData)}, // proposal in epoch 204, IPO in 205, construction and first use in 205 // new contracts should be added above this line #ifdef INCLUDE_CONTRACT_TEST_EXAMPLES {"TESTEXA", 138, 10000, sizeof(TESTEXA::StateData)}, @@ -484,6 +495,7 @@ static void initializeContracts() REGISTER_CONTRACT_FUNCTIONS_AND_PROCEDURES(QTF); REGISTER_CONTRACT_FUNCTIONS_AND_PROCEDURES(QDUEL); REGISTER_CONTRACT_FUNCTIONS_AND_PROCEDURES(PULSE); + REGISTER_CONTRACT_FUNCTIONS_AND_PROCEDURES(VOTTUNBRIDGE); // new contracts should be added above this line #ifdef INCLUDE_CONTRACT_TEST_EXAMPLES REGISTER_CONTRACT_FUNCTIONS_AND_PROCEDURES(TESTEXA); diff --git a/src/contracts/VottunBridge.h b/src/contracts/VottunBridge.h new file mode 100644 index 000000000..6f12d55d2 --- /dev/null +++ b/src/contracts/VottunBridge.h @@ -0,0 +1,2097 @@ +using namespace QPI; + +struct VOTTUNBRIDGE2 +{ +}; + +struct VOTTUNBRIDGE : public ContractBase +{ +public: + // Bridge Order Structure + struct BridgeOrder + { + id qubicSender; // Sender address on Qubic + id qubicDestination; // Destination address on Qubic + Array ethAddress; // Destination Ethereum address + uint64 orderId; // Unique ID for the order + uint64 amount; // Amount to transfer + uint8 orderType; // Type of order (e.g., mint, transfer) + uint8 status; // Order status (e.g., Created, Pending, Refunded) + bit fromQubicToEthereum; // Direction of transfer + bit tokensReceived; // Flag to indicate if tokens have been received + bit tokensLocked; // Flag to indicate if tokens are in locked state + }; + + // Input and Output Structs + struct createOrder_input + { + id qubicDestination; // Destination address on Qubic (for EVM to Qubic orders) + uint64 amount; + Array ethAddress; + bit fromQubicToEthereum; + }; + + struct createOrder_output + { + uint8 status; + uint64 orderId; + }; + + struct getTotalReceivedTokens_input + { + }; + + struct getTotalReceivedTokens_output + { + uint64 totalTokens; + }; + + struct completeOrder_input + { + uint64 orderId; + }; + + struct completeOrder_output + { + uint8 status; + }; + + struct refundOrder_input + { + uint64 orderId; + }; + + struct refundOrder_output + { + uint8 status; + }; + + struct transferToContract_input + { + uint64 amount; + uint64 orderId; + }; + + struct transferToContract_output + { + uint8 status; + }; + + // Get Available Fees structures + struct getAvailableFees_input + { + // No parameters + }; + + struct getAvailableFees_output + { + uint64 availableFees; + uint64 totalEarnedFees; + uint64 totalDistributedFees; + }; + + // Order Response Structure + struct OrderResponse + { + id originAccount; // Origin account + Array destinationAccount; // Destination account + uint64 orderId; // Order ID as uint64 + uint64 amount; // Amount as uint64 + Array memo; // Notes or metadata + uint32 sourceChain; // Source chain identifier + id qubicDestination; + uint8 status; // Order status (0=pending, 1=completed, 2=refunded) + }; + + struct getOrder_input + { + uint64 orderId; + }; + + struct getOrder_output + { + uint8 status; + OrderResponse order; // Updated response format + Array message; + }; + + struct getContractInfo_input + { + // No parameters + }; + + struct getContractInfo_output + { + Array managers; + uint64 nextOrderId; + uint64 lockedTokens; + uint64 totalReceivedTokens; + uint64 earnedFees; + uint32 tradeFeeBillionths; + uint32 sourceChain; + // Debug info + Array firstOrders; // First 16 orders + uint64 totalOrdersFound; // How many non-empty orders exist + uint64 emptySlots; + // Multisig info + Array multisigAdmins; // List of multisig admins + uint8 numberOfAdmins; // Number of active admins + uint8 requiredApprovals; // Required approvals threshold + uint64 totalProposals; // Total number of active proposals + }; + + // Logger structures + struct EthBridgeLogger + { + uint32 _contractIndex; // Index of the contract + uint32 _errorCode; // Error code + uint64 _orderId; // Order ID if applicable + uint64 _amount; // Amount involved in the operation + sint8 _terminator; // Marks the end of the logged data + }; + + struct AddressChangeLogger + { + id _newAdminAddress; + uint32 _contractIndex; + uint8 _eventCode; // Event code 'adminchanged' + sint8 _terminator; + }; + + struct TokensLogger + { + uint32 _contractIndex; + uint64 _lockedTokens; // Balance tokens locked + uint64 _totalReceivedTokens; // Balance total receivedTokens + sint8 _terminator; + }; + + struct getTotalLockedTokens_locals + { + }; + + struct getTotalLockedTokens_input + { + // No input parameters + }; + + struct getTotalLockedTokens_output + { + uint64 totalLockedTokens; + }; + + // Enum for error codes + enum EthBridgeError + { + onlyManagersCanCompleteOrders = 1, + invalidAmount = 2, + insufficientTransactionFee = 3, + orderNotFound = 4, + invalidOrderState = 5, + insufficientLockedTokens = 6, + transferFailed = 7, + maxManagersReached = 8, + notAuthorized = 9, + onlyManagersCanRefundOrders = 10, + proposalNotFound = 11, + proposalAlreadyExecuted = 12, + proposalAlreadyApproved = 13, + notOwner = 14, + maxProposalsReached = 15, + noAvailableSlots = 16, + belowMinimumAmount = 17 + }; + + // Enum for proposal types + enum ProposalType + { + PROPOSAL_SET_ADMIN = 1, + PROPOSAL_ADD_MANAGER = 2, + PROPOSAL_REMOVE_MANAGER = 3, + PROPOSAL_WITHDRAW_FEES = 4, + PROPOSAL_CHANGE_THRESHOLD = 5 + }; + + // Admin proposal structure for multisig + struct AdminProposal + { + uint64 proposalId; + uint8 proposalType; // Type from ProposalType enum + id targetAddress; // For setAdmin/addManager/removeManager (new admin address) + id oldAddress; // For setAdmin: which admin to replace + uint64 amount; // For withdrawFees or changeThreshold + Array approvals; // Array of owner IDs who approved + uint8 approvalsCount; // Count of approvals + bit executed; // Whether proposal was executed + bit active; // Whether proposal is active (not cancelled) + }; + +public: + // Contract State + struct StateData + { + Array orders; + id feeRecipient; // Specific wallet to receive fees + Array managers; // Managers list + uint64 nextOrderId; // Counter for order IDs + uint64 lockedTokens; // Total locked tokens in the contract (balance) + uint64 totalReceivedTokens; // Total tokens received + uint32 sourceChain; // Source chain identifier (e.g., Ethereum=1, Qubic=0) + uint32 _tradeFeeBillionths; // Trade fee in billionths (e.g., 0.5% = 5,000,000) + uint64 _earnedFees; // Accumulated fees from trades + uint64 _distributedFees; // Fees already distributed to shareholders + uint64 _earnedFeesQubic; // Accumulated fees from Qubic trades + uint64 _distributedFeesQubic; // Fees already distributed to Qubic shareholders + uint64 _reservedFees; // Fees reserved for pending orders (not distributed yet) + uint64 _reservedFeesQubic; // Qubic fees reserved for pending orders (not distributed yet) + uint64 minimumOrderAmount; // Minimum order amount to prevent zero-fee spam + + // Multisig state + Array admins; // List of multisig admins + uint8 numberOfAdmins; // Number of active admins + uint8 requiredApprovals; // Threshold: number of approvals needed (2 of 3) + Array proposals; // Pending admin proposals + uint64 nextProposalId; // Counter for proposal IDs + }; + + // Internal methods for admin/manager permissions + typedef id isManager_input; + typedef bit isManager_output; + + struct isManager_locals + { + uint64 i; + }; + + PRIVATE_FUNCTION_WITH_LOCALS(isManager) + { + for (locals.i = 0; locals.i < state.get().managers.capacity(); ++locals.i) + { + if (state.get().managers.get(locals.i) == input) + { + output = true; + return; + } + } + output = false; + } + + typedef id isMultisigAdmin_input; + typedef bit isMultisigAdmin_output; + + struct isMultisigAdmin_locals + { + uint64 i; + }; + + PRIVATE_FUNCTION_WITH_LOCALS(isMultisigAdmin) + { + for (locals.i = 0; locals.i < (uint64)state.get().numberOfAdmins; ++locals.i) + { + if (state.get().admins.get(locals.i) == input) + { + output = true; + return; + } + } + output = false; + } + +public: + // Create a new order and lock tokens + struct createOrder_locals + { + BridgeOrder newOrder; + EthBridgeLogger log; + uint64 i; + uint64 j; + bit slotFound; + bit recyclableFound; + uint64 requiredFeeEth; + uint64 requiredFeeQubic; + uint64 totalRequiredFee; + uint64 invReward; + }; + + PUBLIC_PROCEDURE_WITH_LOCALS(createOrder) + { + // [QVB-11] Capture invocationReward immediately + locals.invReward = qpi.invocationReward(); + + // [QVB-09] Validate minimum order amount (prevents zero-fee spam) + if (input.amount < state.get().minimumOrderAmount) + { + if (locals.invReward > 0) qpi.transfer(qpi.invocator(), locals.invReward); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::belowMinimumAmount, + 0, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::belowMinimumAmount; + return; + } + + // Calculate fees as percentage of amount (0.5% each, 1% total) + locals.requiredFeeEth = div(input.amount * state.get()._tradeFeeBillionths, 1000000000ULL); + locals.requiredFeeQubic = div(input.amount * state.get()._tradeFeeBillionths, 1000000000ULL); + locals.totalRequiredFee = locals.requiredFeeEth + locals.requiredFeeQubic; + + // [QVB-09] Safety check: reject if calculated fee rounds to zero + if (locals.totalRequiredFee == 0) + { + if (locals.invReward > 0) qpi.transfer(qpi.invocator(), locals.invReward); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::insufficientTransactionFee, + 0, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::insufficientTransactionFee; + return; + } + + // [QVB-11] Verify that the fee paid is sufficient + if (static_cast(locals.invReward) < static_cast(locals.totalRequiredFee)) + { + if (locals.invReward > 0) qpi.transfer(qpi.invocator(), locals.invReward); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::insufficientTransactionFee, + 0, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::insufficientTransactionFee; + return; + } + + // [QVB-18] Validate ethAddress is not all zeros (check first 20 bytes) + locals.slotFound = false; // Reuse temporarily as "has non-zero byte" flag + for (locals.i = 0; locals.i < 20; ++locals.i) + { + if (input.ethAddress.get(locals.i) != 0) + { + locals.slotFound = true; + break; + } + } + if (!locals.slotFound) + { + if (locals.invReward > 0) qpi.transfer(qpi.invocator(), locals.invReward); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidAmount, + 0, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidAmount; + return; + } + + // [QVB-17] Set order fields WITHOUT incrementing nextOrderId yet + locals.newOrder.orderId = state.get().nextOrderId; // No ++ here + locals.newOrder.qubicSender = qpi.invocator(); + + // Set qubicDestination according to the direction + if (!input.fromQubicToEthereum) + { + // EVM → Qubic + locals.newOrder.qubicDestination = input.qubicDestination; + + // [QVB-09] Check and RESERVE liquidity + if (state.get().lockedTokens < input.amount) + { + if (locals.invReward > 0) qpi.transfer(qpi.invocator(), locals.invReward); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::insufficientLockedTokens, + 0, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::insufficientLockedTokens; + return; + } + state.mut().lockedTokens -= input.amount; + } + else + { + // Qubic → EVM + locals.newOrder.qubicDestination = qpi.invocator(); + } + + for (locals.i = 0; locals.i < 42; ++locals.i) + { + locals.newOrder.ethAddress.set(locals.i, input.ethAddress.get(locals.i)); + } + locals.newOrder.amount = input.amount; + locals.newOrder.orderType = 0; // Default order type + locals.newOrder.status = 0; // Created + locals.newOrder.fromQubicToEthereum = input.fromQubicToEthereum; + locals.newOrder.tokensReceived = false; + locals.newOrder.tokensLocked = false; + + // [QVB-02] Single-pass slot allocation: find empty slot OR track first recyclable + locals.slotFound = false; + locals.recyclableFound = false; + locals.j = 0; + + for (locals.i = 0; locals.i < state.get().orders.capacity(); ++locals.i) + { + if (state.get().orders.get(locals.i).status == 255) + { + // Empty slot found - use directly + locals.newOrder.orderId = state.mut().nextOrderId++; // [QVB-17] Increment only on success + state.mut().orders.set(locals.i, locals.newOrder); + + state.mut()._earnedFees += locals.requiredFeeEth; + state.mut()._earnedFeesQubic += locals.requiredFeeQubic; + state.mut()._reservedFees += locals.requiredFeeEth; + state.mut()._reservedFeesQubic += locals.requiredFeeQubic; + + // [QVB-11] Refund excess invocationReward + if (locals.invReward > locals.totalRequiredFee) + { + qpi.transfer(qpi.invocator(), locals.invReward - locals.totalRequiredFee); + } + + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, + locals.newOrder.orderId, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = 0; + output.orderId = locals.newOrder.orderId; + return; + } + else if (!locals.recyclableFound && + (state.get().orders.get(locals.i).status == 1 || state.get().orders.get(locals.i).status == 2)) + { + // Track first recyclable slot (completed or refunded) + locals.recyclableFound = true; + locals.j = locals.i; + } + } + + // No empty slot. Try recyclable slot. + if (locals.recyclableFound) + { + locals.newOrder.orderId = state.mut().nextOrderId++; // [QVB-17] Increment only on success + state.mut().orders.set(locals.j, locals.newOrder); + + state.mut()._earnedFees += locals.requiredFeeEth; + state.mut()._earnedFeesQubic += locals.requiredFeeQubic; + state.mut()._reservedFees += locals.requiredFeeEth; + state.mut()._reservedFeesQubic += locals.requiredFeeQubic; + + // [QVB-11] Refund excess invocationReward + if (locals.invReward > locals.totalRequiredFee) + { + qpi.transfer(qpi.invocator(), locals.invReward - locals.totalRequiredFee); + } + + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, + locals.newOrder.orderId, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = 0; + output.orderId = locals.newOrder.orderId; + return; + } + + // [QVB-09] Undo liquidity reservation if we can't create the order + if (!input.fromQubicToEthereum) + { + state.mut().lockedTokens += input.amount; + } + + // No slots available at all - refund everything + if (locals.invReward > 0) qpi.transfer(qpi.invocator(), locals.invReward); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::noAvailableSlots, + 0, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::noAvailableSlots; + return; + } + + // Retrieve an order + struct getOrder_locals + { + EthBridgeLogger log; + BridgeOrder order; + OrderResponse orderResp; + uint64 i; + }; + + PUBLIC_FUNCTION_WITH_LOCALS(getOrder) + { + for (locals.i = 0; locals.i < state.get().orders.capacity(); ++locals.i) + { + locals.order = state.get().orders.get(locals.i); + if (locals.order.orderId == input.orderId && locals.order.status != 255) + { + // Populate OrderResponse with BridgeOrder data + locals.orderResp.orderId = locals.order.orderId; + locals.orderResp.originAccount = locals.order.qubicSender; + locals.orderResp.destinationAccount = locals.order.ethAddress; + locals.orderResp.amount = locals.order.amount; + locals.orderResp.sourceChain = state.get().sourceChain; + locals.orderResp.qubicDestination = locals.order.qubicDestination; + locals.orderResp.status = locals.order.status; + + output.status = 0; // Success + output.order = locals.orderResp; + return; + } + } + + // If order not found + output.status = 1; // Error + } + + // Multisig Proposal Functions + + // Create proposal structures + struct createProposal_input + { + uint8 proposalType; // Type of proposal + id targetAddress; // Target address (new admin/manager address) + id oldAddress; // Old address (for setAdmin: which admin to replace) + uint64 amount; // Amount (for withdrawFees or changeThreshold) + }; + + struct createProposal_output + { + uint8 status; + uint64 proposalId; + }; + + struct createProposal_locals + { + EthBridgeLogger log; + id invocatorAddress; + uint64 i; + uint64 j; + bit slotFound; + bit recyclableFound; + uint64 slotIndex; + AdminProposal newProposal; + bit isMultisigAdminResult; + }; + + // Approve proposal structures + struct approveProposal_input + { + uint64 proposalId; + }; + + struct approveProposal_output + { + uint8 status; + bit executed; + }; + + struct approveProposal_locals + { + EthBridgeLogger log; + id invocatorAddress; + AddressChangeLogger adminLog; + AdminProposal proposal; + uint64 i; + bit found; + bit alreadyApproved; + bit isMultisigAdminResult; + uint64 proposalIndex; + uint64 availableFees; + bit adminAdded; + uint64 managerCount; + bit actionSucceeded; + }; + + // Get proposal structures + struct getProposal_input + { + uint64 proposalId; + }; + + struct getProposal_output + { + uint8 status; + AdminProposal proposal; + }; + + struct getProposal_locals + { + uint64 i; + }; + + // Create a new proposal (only multisig admins can create) + PUBLIC_PROCEDURE_WITH_LOCALS(createProposal) + { + // Verify that the invocator is a multisig admin + locals.invocatorAddress = qpi.invocator(); + CALL(isMultisigAdmin, locals.invocatorAddress, locals.isMultisigAdminResult); + if (!locals.isMultisigAdminResult) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::notOwner, + 0, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::notOwner; + return; + } + + // Validate proposal type + if (input.proposalType < PROPOSAL_SET_ADMIN || input.proposalType > PROPOSAL_CHANGE_THRESHOLD) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidAmount, + 0, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidAmount; + return; + } + + // [QVB-18] Validate targetAddress for proposals that require it + if (input.proposalType == PROPOSAL_SET_ADMIN || + input.proposalType == PROPOSAL_ADD_MANAGER || + input.proposalType == PROPOSAL_REMOVE_MANAGER) + { + if (input.targetAddress == NULL_ID) + { + output.status = EthBridgeError::invalidAmount; + return; + } + } + if (input.proposalType == PROPOSAL_SET_ADMIN) + { + if (input.oldAddress == NULL_ID) + { + output.status = EthBridgeError::invalidAmount; + return; + } + } + + // [QVB-03] Single-pass: find empty slot AND track first recyclable + locals.slotFound = false; + locals.recyclableFound = false; + locals.slotIndex = 0; + locals.j = 0; + + for (locals.i = 0; locals.i < state.get().proposals.capacity(); ++locals.i) + { + if (!state.get().proposals.get(locals.i).active && state.get().proposals.get(locals.i).proposalId == 0) + { + // Empty slot + if (!locals.slotFound) + { + locals.slotFound = true; + locals.slotIndex = locals.i; + } + } + else if (!locals.recyclableFound && + (state.get().proposals.get(locals.i).executed || + (!state.get().proposals.get(locals.i).active && state.get().proposals.get(locals.i).proposalId > 0))) + { + // First recyclable slot (executed or abandoned) + locals.recyclableFound = true; + locals.j = locals.i; + } + } + + // Use empty slot if found, otherwise recycle + if (!locals.slotFound && locals.recyclableFound) + { + // Reuse the recyclable slot directly (will be overwritten with new proposal below) + locals.slotFound = true; + locals.slotIndex = locals.j; + } + + if (!locals.slotFound) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::maxProposalsReached, + 0, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::maxProposalsReached; + return; + } + + // Create the new proposal + locals.newProposal.proposalId = state.mut().nextProposalId++; + locals.newProposal.proposalType = input.proposalType; + locals.newProposal.targetAddress = input.targetAddress; + locals.newProposal.oldAddress = input.oldAddress; + locals.newProposal.amount = input.amount; + locals.newProposal.approvalsCount = 1; // Creator automatically approves + locals.newProposal.executed = false; + locals.newProposal.active = true; + + // Set creator as first approver + locals.newProposal.approvals.set(0, qpi.invocator()); + + // Store the proposal + state.mut().proposals.set(locals.slotIndex, locals.newProposal); + + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, // No error + locals.newProposal.proposalId, + input.amount, + 0 }; + LOG_INFO(locals.log); + + output.status = 0; // Success + output.proposalId = locals.newProposal.proposalId; + } + + // Approve a proposal (only multisig admins can approve) + PUBLIC_PROCEDURE_WITH_LOCALS(approveProposal) + { + // Verify that the invocator is a multisig admin + locals.invocatorAddress = qpi.invocator(); + CALL(isMultisigAdmin, locals.invocatorAddress, locals.isMultisigAdminResult); + if (!locals.isMultisigAdminResult) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::notOwner, + 0, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::notOwner; + output.executed = false; + return; + } + + // Find the proposal + locals.found = false; + for (locals.i = 0; locals.i < state.get().proposals.capacity(); ++locals.i) + { + locals.proposal = state.get().proposals.get(locals.i); + if (locals.proposal.proposalId == input.proposalId && locals.proposal.active) + { + locals.found = true; + locals.proposalIndex = locals.i; + break; + } + } + + if (!locals.found) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::proposalNotFound, + input.proposalId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::proposalNotFound; + output.executed = false; + return; + } + + // Check if already executed + if (locals.proposal.executed) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::proposalAlreadyExecuted, + input.proposalId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::proposalAlreadyExecuted; + output.executed = false; + return; + } + + // Check if this owner has already approved + locals.alreadyApproved = false; + for (locals.i = 0; locals.i < (uint64)locals.proposal.approvalsCount; ++locals.i) + { + if (locals.proposal.approvals.get(locals.i) == qpi.invocator()) + { + locals.alreadyApproved = true; + break; + } + } + + if (locals.alreadyApproved) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::proposalAlreadyApproved, + input.proposalId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::proposalAlreadyApproved; + output.executed = false; + return; + } + + // Add approval + locals.proposal.approvals.set((uint64)locals.proposal.approvalsCount, qpi.invocator()); + locals.proposal.approvalsCount++; + + // Check if threshold reached and execute + if (locals.proposal.approvalsCount >= state.get().requiredApprovals) + { + // [QVB-20] Track whether the action actually succeeded + locals.actionSucceeded = false; + + // Execute the proposal based on type + if (locals.proposal.proposalType == PROPOSAL_SET_ADMIN) + { + // Replace existing admin with new admin (max 3 admins: 2 of 3 multisig) + locals.adminAdded = false; + for (locals.i = 0; locals.i < (uint64)state.get().numberOfAdmins; ++locals.i) + { + if (state.get().admins.get(locals.i) == locals.proposal.targetAddress) + { + locals.adminAdded = true; + break; + } + } + + if (!locals.adminAdded) + { + for (locals.i = 0; locals.i < state.get().admins.capacity(); ++locals.i) + { + if (state.get().admins.get(locals.i) == locals.proposal.oldAddress) + { + state.mut().admins.set(locals.i, locals.proposal.targetAddress); + locals.actionSucceeded = true; + locals.adminLog = AddressChangeLogger{ + locals.proposal.targetAddress, + CONTRACT_INDEX, + 1, // Admin changed + 0 }; + LOG_INFO(locals.adminLog); + break; + } + } + } + } + else if (locals.proposal.proposalType == PROPOSAL_ADD_MANAGER) + { + locals.adminAdded = false; + locals.managerCount = 0; + for (locals.i = 0; locals.i < state.get().managers.capacity(); ++locals.i) + { + if (state.get().managers.get(locals.i) == locals.proposal.targetAddress) + { + locals.adminAdded = true; + break; + } + if (state.get().managers.get(locals.i) != NULL_ID) + { + locals.managerCount++; + } + } + + if (locals.managerCount >= 3) + { + locals.adminAdded = true; + } + + if (!locals.adminAdded) + { + for (locals.i = 0; locals.i < state.get().managers.capacity(); ++locals.i) + { + if (state.get().managers.get(locals.i) == NULL_ID) + { + state.mut().managers.set(locals.i, locals.proposal.targetAddress); + locals.actionSucceeded = true; + locals.adminLog = AddressChangeLogger{ + locals.proposal.targetAddress, + CONTRACT_INDEX, + 2, // Manager added + 0 }; + LOG_INFO(locals.adminLog); + break; + } + } + } + } + else if (locals.proposal.proposalType == PROPOSAL_REMOVE_MANAGER) + { + for (locals.i = 0; locals.i < state.get().managers.capacity(); ++locals.i) + { + if (state.get().managers.get(locals.i) == locals.proposal.targetAddress) + { + state.mut().managers.set(locals.i, NULL_ID); + locals.actionSucceeded = true; + locals.adminLog = AddressChangeLogger{ + locals.proposal.targetAddress, + CONTRACT_INDEX, + 3, // Manager removed + 0 }; + LOG_INFO(locals.adminLog); + break; + } + } + } + else if (locals.proposal.proposalType == PROPOSAL_WITHDRAW_FEES) + { + locals.availableFees = (state.get()._earnedFees > (state.get()._distributedFees + state.get()._reservedFees)) + ? (state.get()._earnedFees - state.get()._distributedFees - state.get()._reservedFees) + : 0; + if (locals.proposal.amount <= locals.availableFees && locals.proposal.amount > 0) + { + if (qpi.transfer(state.get().feeRecipient, locals.proposal.amount) >= 0) + { + state.mut()._distributedFees += locals.proposal.amount; + locals.actionSucceeded = true; + } + } + } + else if (locals.proposal.proposalType == PROPOSAL_CHANGE_THRESHOLD) + { + if (locals.proposal.amount >= 2 && locals.proposal.amount <= (uint64)state.get().numberOfAdmins) + { + state.mut().requiredApprovals = (uint8)locals.proposal.amount; + locals.actionSucceeded = true; + } + } + + // [QVB-20] Only mark as executed if action actually succeeded + if (locals.actionSucceeded) + { + locals.proposal.executed = true; + output.executed = true; + } + else + { + // Action failed - deactivate proposal so admins can create a new one + locals.proposal.active = false; + output.executed = false; + + state.mut().proposals.set(locals.proposalIndex, locals.proposal); + + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidOrderState, + input.proposalId, + locals.proposal.approvalsCount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidOrderState; + return; + } + } + else + { + output.executed = false; + } + + // Update the proposal + state.mut().proposals.set(locals.proposalIndex, locals.proposal); + + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, // No error + input.proposalId, + locals.proposal.approvalsCount, + 0 }; + LOG_INFO(locals.log); + + output.status = 0; // Success + } + + // Get proposal details + PUBLIC_FUNCTION_WITH_LOCALS(getProposal) + { + for (locals.i = 0; locals.i < state.get().proposals.capacity(); ++locals.i) + { + if (state.get().proposals.get(locals.i).proposalId == input.proposalId) + { + output.proposal = state.get().proposals.get(locals.i); + output.status = 0; // Success + return; + } + } + + output.status = EthBridgeError::proposalNotFound; + } + + // Cancel proposal structures + struct cancelProposal_input + { + uint64 proposalId; + }; + + struct cancelProposal_output + { + uint8 status; + }; + + struct cancelProposal_locals + { + EthBridgeLogger log; + AdminProposal proposal; + uint64 i; + bit found; + }; + + // Cancel a proposal (only the creator can cancel) + PUBLIC_PROCEDURE_WITH_LOCALS(cancelProposal) + { + // Find the proposal + locals.found = false; + for (locals.i = 0; locals.i < state.get().proposals.capacity(); ++locals.i) + { + locals.proposal = state.get().proposals.get(locals.i); + if (locals.proposal.proposalId == input.proposalId && locals.proposal.active) + { + locals.found = true; + break; + } + } + + if (!locals.found) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::proposalNotFound, + input.proposalId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::proposalNotFound; + return; + } + + // Check if already executed + if (locals.proposal.executed) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::proposalAlreadyExecuted, + input.proposalId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::proposalAlreadyExecuted; + return; + } + + // Verify that the invocator is the creator (first approver) + if (locals.proposal.approvals.get(0) != qpi.invocator()) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::notAuthorized, + input.proposalId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::notAuthorized; + return; + } + + // Cancel the proposal by marking it as inactive + locals.proposal.active = false; + state.mut().proposals.set(locals.i, locals.proposal); + + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, // No error + input.proposalId, + 0, + 0 }; + LOG_INFO(locals.log); + + output.status = 0; // Success + } + + struct getTotalReceivedTokens_locals + { + }; + + PUBLIC_FUNCTION_WITH_LOCALS(getTotalReceivedTokens) + { + output.totalTokens = state.get().totalReceivedTokens; + } + + struct completeOrder_locals + { + EthBridgeLogger log; + id invocatorAddress; + bit isManagerOperating; + bit orderFound; + BridgeOrder order; + TokensLogger logTokens; + uint64 i; + uint64 feeOperator; + uint64 feeNetwork; + }; + + // Complete an order and release tokens + PUBLIC_PROCEDURE_WITH_LOCALS(completeOrder) + { + locals.invocatorAddress = qpi.invocator(); + locals.isManagerOperating = false; + CALL(isManager, locals.invocatorAddress, locals.isManagerOperating); + + // Verify that the invocator is a manager + if (!locals.isManagerOperating) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::onlyManagersCanCompleteOrders, + input.orderId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::onlyManagersCanCompleteOrders; // Error: not a manager + return; + } + + // Check if the order exists + locals.orderFound = false; + for (locals.i = 0; locals.i < state.get().orders.capacity(); ++locals.i) + { + if (state.get().orders.get(locals.i).orderId == input.orderId) + { + locals.order = state.get().orders.get(locals.i); + locals.orderFound = true; + break; + } + } + + // Order not found + if (!locals.orderFound) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::orderNotFound, + input.orderId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::orderNotFound; // Error + return; + } + + // Check order status + if (locals.order.status != 0) + { // Check it is not completed or refunded already + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidOrderState, + input.orderId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidOrderState; // Error + return; + } + + // Handle order based on transfer direction + if (locals.order.fromQubicToEthereum) + { + // Qubic → Ethereum + // [QVB-21] Only check that tokens were received (tokensLocked is set here as part of two-phase commit) + if (!locals.order.tokensReceived) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidOrderState, + input.orderId, + locals.order.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidOrderState; + return; + } + + // [QVB-21] Set tokensLocked as part of completion (two-phase commit) + locals.order.tokensLocked = true; + } + else + { + // EVM → Qubic + // [QVB-09] Liquidity already reserved at createOrder - just transfer to user + // [QVB-04] Use locals.order.amount directly (removed redundant netAmount) + if (qpi.transfer(locals.order.qubicDestination, locals.order.amount) < 0) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::transferFailed, + input.orderId, + locals.order.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::transferFailed; + return; + } + + locals.logTokens = TokensLogger{ + CONTRACT_INDEX, + state.get().lockedTokens, + state.get().totalReceivedTokens, + 0 }; + LOG_INFO(locals.logTokens); + } + + // Release reserved fees now that order is completed (fees can now be distributed) + locals.feeOperator = div(locals.order.amount * state.get()._tradeFeeBillionths, 1000000000ULL); + locals.feeNetwork = div(locals.order.amount * state.get()._tradeFeeBillionths, 1000000000ULL); + + // UNDERFLOW PROTECTION: Only release if enough reserved + if (state.get()._reservedFees >= locals.feeOperator) + { + state.mut()._reservedFees -= locals.feeOperator; + } + if (state.get()._reservedFeesQubic >= locals.feeNetwork) + { + state.mut()._reservedFeesQubic -= locals.feeNetwork; + } + + // Mark the order as completed + locals.order.status = 1; // Completed + state.mut().orders.set(locals.i, locals.order); // Use the loop index + + output.status = 0; // Success + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, // No error + input.orderId, + locals.order.amount, + 0 }; + LOG_INFO(locals.log); + } + + // Refund an order and unlock tokens + struct refundOrder_locals + { + EthBridgeLogger log; + id invocatorAddress; + bit isManagerOperating; + bit orderFound; + BridgeOrder order; + uint64 i; + uint64 feeOperator; + uint64 feeNetwork; + uint64 totalRefund; + }; + + PUBLIC_PROCEDURE_WITH_LOCALS(refundOrder) + { + locals.invocatorAddress = qpi.invocator(); + locals.isManagerOperating = false; + CALL(isManager, locals.invocatorAddress, locals.isManagerOperating); + + // Check if the order is handled by a manager + if (!locals.isManagerOperating) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::onlyManagersCanRefundOrders, + input.orderId, + 0, // No amount involved + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::onlyManagersCanRefundOrders; // Error + return; + } + + // Retrieve the order + locals.orderFound = false; + for (locals.i = 0; locals.i < state.get().orders.capacity(); ++locals.i) + { + if (state.get().orders.get(locals.i).orderId == input.orderId) + { + locals.order = state.get().orders.get(locals.i); + locals.orderFound = true; + break; + } + } + + // Order not found + if (!locals.orderFound) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::orderNotFound, + input.orderId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::orderNotFound; // Error + return; + } + + // Check order status + if (locals.order.status != 0) + { // Check it is not completed or refunded already + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidOrderState, + input.orderId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidOrderState; // Error + return; + } + + // Calculate fees for this order + locals.feeOperator = div(locals.order.amount * state.get()._tradeFeeBillionths, 1000000000ULL); + locals.feeNetwork = div(locals.order.amount * state.get()._tradeFeeBillionths, 1000000000ULL); + + // Handle refund based on transfer direction + if (locals.order.fromQubicToEthereum) + { + // Qubic → Ethereum refund + if (!locals.order.tokensReceived) + { + // Path A: No tokens transferred yet - refund only fees + // [QVB-12] Calculate refund amount WITHOUT modifying state first + locals.totalRefund = 0; + if (state.get()._reservedFees >= locals.feeOperator && state.get()._earnedFees >= locals.feeOperator) + { + locals.totalRefund += locals.feeOperator; + } + if (state.get()._reservedFeesQubic >= locals.feeNetwork && state.get()._earnedFeesQubic >= locals.feeNetwork) + { + locals.totalRefund += locals.feeNetwork; + } + + // Transfer first - if it fails, no state is corrupted + if (locals.totalRefund > 0) + { + if (qpi.transfer(locals.order.qubicSender, locals.totalRefund) < 0) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::transferFailed, + input.orderId, + locals.totalRefund, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::transferFailed; + return; + } + } + + // [QVB-12] Only update state AFTER successful transfer + if (state.get()._reservedFees >= locals.feeOperator && state.get()._earnedFees >= locals.feeOperator) + { + state.mut()._reservedFees -= locals.feeOperator; + state.mut()._earnedFees -= locals.feeOperator; + } + if (state.get()._reservedFeesQubic >= locals.feeNetwork && state.get()._earnedFeesQubic >= locals.feeNetwork) + { + state.mut()._reservedFeesQubic -= locals.feeNetwork; + state.mut()._earnedFeesQubic -= locals.feeNetwork; + } + + locals.order.status = 2; + state.mut().orders.set(locals.i, locals.order); + + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, + input.orderId, + locals.totalRefund, + 0 }; + LOG_INFO(locals.log); + output.status = 0; + return; + } + else + { + // Path B: Tokens received - refund amount + fees + // [QVB-21] Handles both !tokensLocked (intermediate) and tokensLocked (defensive) states + if (state.get().lockedTokens < locals.order.amount) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::insufficientLockedTokens, + input.orderId, + locals.order.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::insufficientLockedTokens; + return; + } + + // [QVB-12] Calculate total refund WITHOUT modifying state + locals.totalRefund = locals.order.amount; + if (state.get()._reservedFees >= locals.feeOperator && state.get()._earnedFees >= locals.feeOperator) + { + locals.totalRefund += locals.feeOperator; + } + if (state.get()._reservedFeesQubic >= locals.feeNetwork && state.get()._earnedFeesQubic >= locals.feeNetwork) + { + locals.totalRefund += locals.feeNetwork; + } + + // Transfer first + if (qpi.transfer(locals.order.qubicSender, locals.totalRefund) < 0) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::transferFailed, + input.orderId, + locals.totalRefund, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::transferFailed; + return; + } + + // [QVB-12] Update state only after successful transfer + state.mut().lockedTokens -= locals.order.amount; + if (state.get()._reservedFees >= locals.feeOperator && state.get()._earnedFees >= locals.feeOperator) + { + state.mut()._reservedFees -= locals.feeOperator; + state.mut()._earnedFees -= locals.feeOperator; + } + if (state.get()._reservedFeesQubic >= locals.feeNetwork && state.get()._earnedFeesQubic >= locals.feeNetwork) + { + state.mut()._reservedFeesQubic -= locals.feeNetwork; + state.mut()._earnedFeesQubic -= locals.feeNetwork; + } + + locals.order.status = 2; + state.mut().orders.set(locals.i, locals.order); + + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, + input.orderId, + locals.totalRefund, + 0 }; + LOG_INFO(locals.log); + output.status = 0; + return; + } + } + else + { + // EVM → Qubic refund + // [QVB-09] Restore reserved liquidity (was decremented at createOrder) + state.mut().lockedTokens += locals.order.amount; + + // Release fee reserves (fees stay earned - paid by bridge operator, not end user) + if (state.get()._reservedFees >= locals.feeOperator) + { + state.mut()._reservedFees -= locals.feeOperator; + } + if (state.get()._reservedFeesQubic >= locals.feeNetwork) + { + state.mut()._reservedFeesQubic -= locals.feeNetwork; + } + + locals.order.status = 2; + state.mut().orders.set(locals.i, locals.order); + + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, + input.orderId, + locals.order.amount, + 0 }; + LOG_INFO(locals.log); + output.status = 0; + return; + } + } + + // Transfer tokens to the contract + struct transferToContract_locals + { + EthBridgeLogger log; + TokensLogger logTokens; + BridgeOrder order; + bit orderFound; + uint64 i; + uint64 depositAmount; + }; + + PUBLIC_PROCEDURE_WITH_LOCALS(transferToContract) + { + // [QVB-10] Capture invocationReward immediately so we can refund on any error + locals.depositAmount = qpi.invocationReward(); + + if (input.amount == 0) + { + if (locals.depositAmount > 0) qpi.transfer(qpi.invocator(), locals.depositAmount); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidAmount, + input.orderId, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidAmount; + return; + } + + // Find the order + locals.orderFound = false; + for (locals.i = 0; locals.i < state.get().orders.capacity(); ++locals.i) + { + if (state.get().orders.get(locals.i).orderId == input.orderId) + { + locals.order = state.get().orders.get(locals.i); + locals.orderFound = true; + break; + } + } + + if (!locals.orderFound) + { + if (locals.depositAmount > 0) qpi.transfer(qpi.invocator(), locals.depositAmount); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::orderNotFound, + input.orderId, + 0, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::orderNotFound; + return; + } + + // Verify sender is the original order creator + if (locals.order.qubicSender != qpi.invocator()) + { + if (locals.depositAmount > 0) qpi.transfer(qpi.invocator(), locals.depositAmount); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::notAuthorized, + input.orderId, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::notAuthorized; + return; + } + + // Verify order state + if (locals.order.status != 0) + { + if (locals.depositAmount > 0) qpi.transfer(qpi.invocator(), locals.depositAmount); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidOrderState, + input.orderId, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidOrderState; + return; + } + + // Verify tokens not already received + if (locals.order.tokensReceived) + { + if (locals.depositAmount > 0) qpi.transfer(qpi.invocator(), locals.depositAmount); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidOrderState, + input.orderId, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidOrderState; + return; + } + + // Verify amount matches order + if (input.amount != locals.order.amount) + { + if (locals.depositAmount > 0) qpi.transfer(qpi.invocator(), locals.depositAmount); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidAmount, + input.orderId, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidAmount; + return; + } + + // [QVB-22] Reject EVM→Qubic orders (they don't need transferToContract) + if (!locals.order.fromQubicToEthereum) + { + if (locals.depositAmount > 0) qpi.transfer(qpi.invocator(), locals.depositAmount); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidOrderState, + input.orderId, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidOrderState; + return; + } + + // Only Qubic→Ethereum orders proceed from here + // Check if user sent enough tokens + if (locals.depositAmount < input.amount) + { + // Not enough - refund everything and return error + if (locals.depositAmount > 0) + { + qpi.transfer(qpi.invocator(), locals.depositAmount); + } + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidAmount, + input.orderId, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidAmount; + return; + } + + // Lock only the required amount + state.mut().lockedTokens += input.amount; + state.mut().totalReceivedTokens += input.amount; + + // Refund excess if user sent too much + if (locals.depositAmount > input.amount) + { + qpi.transfer(qpi.invocator(), locals.depositAmount - input.amount); + } + + // [QVB-21] Only mark tokens as received, NOT locked + // tokensLocked will be set by completeOrder (two-phase commit) + locals.order.tokensReceived = true; + state.mut().orders.set(locals.i, locals.order); + + locals.logTokens = TokensLogger{ + CONTRACT_INDEX, + state.get().lockedTokens, + state.get().totalReceivedTokens, + 0 }; + LOG_INFO(locals.logTokens); + + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, + input.orderId, + input.amount, + 0 }; + LOG_INFO(locals.log); + output.status = 0; + } + + PUBLIC_FUNCTION_WITH_LOCALS(getTotalLockedTokens) + { + output.totalLockedTokens = state.get().lockedTokens; + } + + // Structure for the input of the getOrderByDetails function + struct getOrderByDetails_input + { + Array ethAddress; // Ethereum address + uint64 amount; // Transaction amount + uint8 status; // Order status (0 = created, 1 = completed, 2 = refunded) + }; + + // Structure for the output of the getOrderByDetails function + struct getOrderByDetails_output + { + uint8 status; // Operation status (0 = success, other = error) + uint64 orderId; // ID of the found order + id qubicDestination; // Destination address on Qubic (for EVM to Qubic orders) + }; + + // Function to search for an order by details + struct getOrderByDetails_locals + { + uint64 i; + uint64 j; + bit addressMatch; // Flag to check if addresses match + BridgeOrder order; + }; + + PUBLIC_FUNCTION_WITH_LOCALS(getOrderByDetails) + { + // Validate input parameters + if (input.amount == 0) + { + output.status = 2; // Error: invalid amount + output.orderId = 0; + return; + } + + // Iterate through all orders + for (locals.i = 0; locals.i < state.get().orders.capacity(); ++locals.i) + { + locals.order = state.get().orders.get(locals.i); + + // Check if the order matches the criteria + if (locals.order.status == 255) // Empty slot + continue; + + // Compare ethAddress arrays element by element + locals.addressMatch = true; + for (locals.j = 0; locals.j < 42; ++locals.j) + { + if (locals.order.ethAddress.get(locals.j) != input.ethAddress.get(locals.j)) + { + locals.addressMatch = false; + break; + } + } + + // Verify exact match + if (locals.addressMatch && + locals.order.amount == input.amount && + locals.order.status == input.status) + { + // Found an exact match + output.status = 0; // Success + output.orderId = locals.order.orderId; + return; + } + } + + // If no matching order was found + output.status = 1; // Not found + output.orderId = 0; + } + + // Add Liquidity structures + struct addLiquidity_input + { + // No input parameters - amount comes from qpi.invocationReward() + }; + + struct addLiquidity_output + { + uint8 status; // Operation status (0 = success, other = error) + uint64 addedAmount; // Amount of tokens added to liquidity + uint64 totalLocked; // Total locked tokens after addition + }; + + struct addLiquidity_locals + { + EthBridgeLogger log; + id invocatorAddress; + bit isManagerOperating; + bit isMultisigAdminResult; + uint64 depositAmount; + }; + + // Add liquidity to the bridge (for managers or multisig admins to provide initial/additional liquidity) + PUBLIC_PROCEDURE_WITH_LOCALS(addLiquidity) + { + locals.invocatorAddress = qpi.invocator(); + + // [QVB-10] Capture deposit immediately so we can refund on auth failure + locals.depositAmount = qpi.invocationReward(); + + locals.isManagerOperating = false; + CALL(isManager, locals.invocatorAddress, locals.isManagerOperating); + + locals.isMultisigAdminResult = false; + CALL(isMultisigAdmin, locals.invocatorAddress, locals.isMultisigAdminResult); + + // Verify that the invocator is a manager or multisig admin + if (!locals.isManagerOperating && !locals.isMultisigAdminResult) + { + // [QVB-10] Refund before returning + if (locals.depositAmount > 0) qpi.transfer(qpi.invocator(), locals.depositAmount); + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::notAuthorized, + 0, + 0, + 0 + }; + LOG_INFO(locals.log); + output.status = EthBridgeError::notAuthorized; + return; + } + + // Validate that some tokens were sent + if (locals.depositAmount == 0) + { + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + EthBridgeError::invalidAmount, + 0, + 0, + 0 + }; + LOG_INFO(locals.log); + output.status = EthBridgeError::invalidAmount; + return; + } + + // Add the deposited tokens to the locked tokens pool + state.mut().lockedTokens += locals.depositAmount; + state.mut().totalReceivedTokens += locals.depositAmount; + + // Log the successful liquidity addition + locals.log = EthBridgeLogger{ + CONTRACT_INDEX, + 0, // No error + 0, // No order ID involved + locals.depositAmount, // Amount added + 0 + }; + LOG_INFO(locals.log); + + // Set output values + output.status = 0; // Success + output.addedAmount = locals.depositAmount; + output.totalLocked = state.get().lockedTokens; + } + + + PUBLIC_FUNCTION(getAvailableFees) + { + // Available fees exclude those reserved for pending orders + output.availableFees = (state.get()._earnedFees > (state.get()._distributedFees + state.get()._reservedFees)) + ? (state.get()._earnedFees - state.get()._distributedFees - state.get()._reservedFees) + : 0; + output.totalEarnedFees = state.get()._earnedFees; + output.totalDistributedFees = state.get()._distributedFees; + } + + + struct getContractInfo_locals + { + uint64 i; + }; + + PUBLIC_FUNCTION_WITH_LOCALS(getContractInfo) + { + output.managers = state.get().managers; + output.nextOrderId = state.get().nextOrderId; + output.lockedTokens = state.get().lockedTokens; + output.totalReceivedTokens = state.get().totalReceivedTokens; + output.earnedFees = state.get()._earnedFees; + output.tradeFeeBillionths = state.get()._tradeFeeBillionths; + output.sourceChain = state.get().sourceChain; + + + output.totalOrdersFound = 0; + output.emptySlots = 0; + + for (locals.i = 0; locals.i < 16 && locals.i < state.get().orders.capacity(); ++locals.i) + { + output.firstOrders.set(locals.i, state.get().orders.get(locals.i)); + } + + // Count real orders vs empty ones + for (locals.i = 0; locals.i < state.get().orders.capacity(); ++locals.i) + { + if (state.get().orders.get(locals.i).status == 255) + { + output.emptySlots++; + } + else + { + output.totalOrdersFound++; + } + } + + // Multisig info + output.multisigAdmins = state.get().admins; + output.numberOfAdmins = state.get().numberOfAdmins; + output.requiredApprovals = state.get().requiredApprovals; + + // Count active proposals + output.totalProposals = 0; + for (locals.i = 0; locals.i < state.get().proposals.capacity(); ++locals.i) + { + if (state.get().proposals.get(locals.i).active && state.get().proposals.get(locals.i).proposalId > 0) + { + output.totalProposals++; + } + } + } + + // Called at the end of every tick to distribute earned fees + struct END_TICK_locals + { + uint64 feesToDistributeInThisTick; + uint64 amountPerComputor; + uint64 vottunFeesToDistribute; + }; + + END_TICK_WITH_LOCALS() + { + // Calculate available fees for distribution (earned - distributed - reserved for pending orders) + locals.feesToDistributeInThisTick = (state.get()._earnedFeesQubic > (state.get()._distributedFeesQubic + state.get()._reservedFeesQubic)) + ? (state.get()._earnedFeesQubic - state.get()._distributedFeesQubic - state.get()._reservedFeesQubic) + : 0; + + if (locals.feesToDistributeInThisTick > 0) + { + // Distribute fees to computors holding shares of this contract. + // NUMBER_OF_COMPUTORS is a Qubic global constant (typically 676). + locals.amountPerComputor = div(locals.feesToDistributeInThisTick, (uint64)NUMBER_OF_COMPUTORS); + + if (locals.amountPerComputor > 0) + { + if (qpi.distributeDividends(locals.amountPerComputor)) + { + state.mut()._distributedFeesQubic += locals.amountPerComputor * NUMBER_OF_COMPUTORS; + } + } + } + + // Distribution of Vottun fees to feeRecipient (excluding reserved fees) + locals.vottunFeesToDistribute = (state.get()._earnedFees > (state.get()._distributedFees + state.get()._reservedFees)) + ? (state.get()._earnedFees - state.get()._distributedFees - state.get()._reservedFees) + : 0; + + if (locals.vottunFeesToDistribute > 0 && state.get().feeRecipient != NULL_ID) + { + // [QVB-13] Check for non-negative return (success), not truthy (which -1 also satisfies) + if (qpi.transfer(state.get().feeRecipient, locals.vottunFeesToDistribute) >= 0) + { + state.mut()._distributedFees += locals.vottunFeesToDistribute; + } + } + } + + // Register Functions and Procedures + REGISTER_USER_FUNCTIONS_AND_PROCEDURES() + { + REGISTER_USER_FUNCTION(getOrder, 1); + REGISTER_USER_FUNCTION(isManager, 2); + REGISTER_USER_FUNCTION(getTotalReceivedTokens, 3); + REGISTER_USER_FUNCTION(getTotalLockedTokens, 4); + REGISTER_USER_FUNCTION(getOrderByDetails, 5); + REGISTER_USER_FUNCTION(getContractInfo, 6); + REGISTER_USER_FUNCTION(getAvailableFees, 7); + REGISTER_USER_FUNCTION(getProposal, 8); + + REGISTER_USER_PROCEDURE(createOrder, 1); + REGISTER_USER_PROCEDURE(completeOrder, 2); + REGISTER_USER_PROCEDURE(refundOrder, 3); + REGISTER_USER_PROCEDURE(transferToContract, 4); + REGISTER_USER_PROCEDURE(addLiquidity, 5); + REGISTER_USER_PROCEDURE(createProposal, 6); + REGISTER_USER_PROCEDURE(approveProposal, 7); + REGISTER_USER_PROCEDURE(cancelProposal, 8); + } + + // Initialize the contract with SECURE ADMIN CONFIGURATION + struct INITIALIZE_locals + { + uint64 i; + BridgeOrder emptyOrder; + AdminProposal emptyProposal; + }; + + INITIALIZE_WITH_LOCALS() + { + // Initialize the wallet that receives operator fees (Vottun) + state.mut().feeRecipient = ID(_M, _A, _G, _K, _B, _C, _B, _I, _X, _N, _W, _S, _K, _C, _I, _G, _J, _Y, _K, _G, _S, _N, _F, _S, _F, _R, _W, _A, _L, _H, _D, _F, _D, _B, _K, _K, _P, _C, _U, _N, _S, _E, _R, _I, _K, _L, _J, _G, _M, _D, _K, _L, _Z, _V, _V, _D); + + // Initialize the orders array. Good practice to zero first. + locals.emptyOrder = {}; // Sets all fields to 0 (including orderId and status). + locals.emptyOrder.status = 255; // Then set your status for empty. + + for (locals.i = 0; locals.i < state.get().orders.capacity(); ++locals.i) + { + state.mut().orders.set(locals.i, locals.emptyOrder); + } + + // Initialize the managers array with NULL_ID to mark slots as empty + for (locals.i = 0; locals.i < state.get().managers.capacity(); ++locals.i) + { + state.mut().managers.set(locals.i, NULL_ID); + } + + // Add the initial manager + state.mut().managers.set(0, ID(_U, _X, _V, _K, _B, _Y, _L, _Q, _Z, _I, _U, _L, _C, _B, _F, _F, _I, _L, _P, _T, _X, _O, _W, _Y, _M, _Y, _H, _D, _K, _P, _R, _Y, _W, _R, _E, _Y, _Q, _T, _Y, _Y, _A, _C, _T, _F, _W, _Q, _V, _O, _N, _P, _F, _E, _L, _P, _G, _A)); + + // Initialize the rest of the state variables + state.mut().nextOrderId = 1; // Start from 1 to avoid ID 0 + state.mut().lockedTokens = 0; + state.mut().totalReceivedTokens = 0; + state.mut().sourceChain = 0; // Arbitrary number. No-EVM chain + + // Initialize fee variables + state.mut()._tradeFeeBillionths = 5000000; // 0.5% == 5,000,000 / 1,000,000,000 + state.mut()._earnedFees = 0; + state.mut()._distributedFees = 0; + + state.mut()._earnedFeesQubic = 0; + state.mut()._distributedFeesQubic = 0; + + state.mut()._reservedFees = 0; + state.mut()._reservedFeesQubic = 0; + + // [QVB-09] Minimum order amount to prevent zero-fee spam + state.mut().minimumOrderAmount = 200; // Minimum 200 QU (fee = 1 QU per direction) + + // Initialize multisig admins (3 admins, requires 2 approvals) + state.mut().numberOfAdmins = 3; + state.mut().requiredApprovals = 2; // 2 of 3 threshold + + // Initialize admins array (REPLACE WITH ACTUAL ADMIN ADDRESSES) + state.mut().admins.set(0, ID(_U, _X, _V, _K, _B, _Y, _L, _Q, _Z, _I, _U, _L, _C, _B, _F, _F, _I, _L, _P, _T, _X, _O, _W, _Y, _M, _Y, _H, _D, _K, _P, _R, _Y, _W, _R, _E, _Y, _Q, _T, _Y, _Y, _A, _C, _T, _F, _W, _Q, _V, _O, _N, _P, _F, _E, _L, _P, _G, _A)); // Admin 1 + state.mut().admins.set(1, ID(_D, _F, _A, _C, _O, _J, _K, _F, _A, _F, _M, _V, _J, _B, _I, _X, _K, _C, _K, _N, _A, _Y, _S, _T, _B, _S, _D, _D, _X, _Y, _I, _A, _Y, _J, _Q, _P, _H, _Y, _D, _V, _D, _H, _A, _S, _B, _A, _T, _H, _A, _L, _D, _C, _O, _Q, _K, _F)); // Admin 2 (Manager) + state.mut().admins.set(2, ID(_O, _U, _T, _P, _L, _M, _H, _I, _P, _V, _D, _X, _P, _D, _J, _R, _S, _O, _D, _R, _A, _O, _U, _L, _V, _D, _V, _A, _T, _I, _D, _W, _X, _X, _L, _Q, _O, _F, _X, _O, _D, _D, _X, _P, _J, _M, _Q, _G, _C, _S, _J, _Y, _Q, _Q, _V, _D)); // Admin 3 (User) + + // Initialize remaining admin slots + for (locals.i = 3; locals.i < state.get().admins.capacity(); ++locals.i) + { + state.mut().admins.set(locals.i, NULL_ID); + } + + // Initialize proposals array properly (like orders array) + state.mut().nextProposalId = 1; + + // Initialize emptyProposal fields explicitly (avoid memset) + locals.emptyProposal.proposalId = 0; + locals.emptyProposal.proposalType = 0; + locals.emptyProposal.targetAddress = NULL_ID; + locals.emptyProposal.amount = 0; + locals.emptyProposal.approvalsCount = 0; + locals.emptyProposal.executed = false; + locals.emptyProposal.active = false; + // Initialize approvals array with NULL_ID + for (locals.i = 0; locals.i < locals.emptyProposal.approvals.capacity(); ++locals.i) + { + locals.emptyProposal.approvals.set(locals.i, NULL_ID); + } + + // Set all proposal slots with the empty proposal + for (locals.i = 0; locals.i < state.get().proposals.capacity(); ++locals.i) + { + state.mut().proposals.set(locals.i, locals.emptyProposal); + } + } +}; diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index 6723ec0a1..d429b8716 100644 --- a/test/CMakeLists.txt +++ b/test/CMakeLists.txt @@ -33,6 +33,7 @@ add_executable( # contract_qearn.cpp # contract_qvault.cpp # contract_qx.cpp + contract_vottunbridge.cpp # kangaroo_twelve.cpp m256.cpp math_lib.cpp diff --git a/test/contract_vottunbridge.cpp b/test/contract_vottunbridge.cpp new file mode 100644 index 000000000..b1b055296 --- /dev/null +++ b/test/contract_vottunbridge.cpp @@ -0,0 +1,916 @@ +#define NO_UEFI + +#include + +#include "contract_testing.h" + +namespace { +constexpr unsigned short PROCEDURE_CREATE_ORDER = 1; +constexpr unsigned short PROCEDURE_TRANSFER_TO_CONTRACT = 4; + +uint64 requiredFee(uint64 amount) +{ + // Total fee is 0.5% (ETH) + 0.5% (Qubic) = 1% of amount + return 2 * ((amount * 5000000ULL) / 1000000000ULL); +} +} + +class ContractTestingVottunBridge : protected ContractTesting +{ +public: + using ContractTesting::invokeUserProcedure; + + ContractTestingVottunBridge() + { + initEmptySpectrum(); + initEmptyUniverse(); + INIT_CONTRACT(VOTTUNBRIDGE); + callSystemProcedure(VOTTUNBRIDGE_CONTRACT_INDEX, INITIALIZE); + } + + VOTTUNBRIDGE::StateData* state() + { + return reinterpret_cast(contractStates[VOTTUNBRIDGE_CONTRACT_INDEX]); + } + + bool findOrder(uint64 orderId, VOTTUNBRIDGE::BridgeOrder& out) + { + for (uint64 i = 0; i < state()->orders.capacity(); ++i) + { + VOTTUNBRIDGE::BridgeOrder order = state()->orders.get(i); + if (order.orderId == orderId) + { + out = order; + return true; + } + } + return false; + } + + bool findProposal(uint64 proposalId, VOTTUNBRIDGE::AdminProposal& out) + { + for (uint64 i = 0; i < state()->proposals.capacity(); ++i) + { + VOTTUNBRIDGE::AdminProposal proposal = state()->proposals.get(i); + if (proposal.proposalId == proposalId) + { + out = proposal; + return true; + } + } + return false; + } + + bool setOrderById(uint64 orderId, const VOTTUNBRIDGE::BridgeOrder& updated) + { + for (uint64 i = 0; i < state()->orders.capacity(); ++i) + { + VOTTUNBRIDGE::BridgeOrder order = state()->orders.get(i); + if (order.orderId == orderId) + { + state()->orders.set(i, updated); + return true; + } + } + return false; + } + + bool setProposalById(uint64 proposalId, const VOTTUNBRIDGE::AdminProposal& updated) + { + for (uint64 i = 0; i < state()->proposals.capacity(); ++i) + { + VOTTUNBRIDGE::AdminProposal proposal = state()->proposals.get(i); + if (proposal.proposalId == proposalId) + { + state()->proposals.set(i, updated); + return true; + } + } + return false; + } + + VOTTUNBRIDGE::createOrder_output createOrder( + const id& user, uint64 amount, bit fromQubicToEthereum, uint64 fee) + { + VOTTUNBRIDGE::createOrder_input input{}; + VOTTUNBRIDGE::createOrder_output output{}; + input.qubicDestination = id(9, 0, 0, 0); + input.amount = amount; + input.fromQubicToEthereum = fromQubicToEthereum; + for (uint64 i = 0; i < 42; ++i) + { + input.ethAddress.set(i, static_cast('A')); + } + + this->invokeUserProcedure(VOTTUNBRIDGE_CONTRACT_INDEX, PROCEDURE_CREATE_ORDER, + input, output, user, static_cast(fee)); + return output; + } + + void seedBalance(const id& user, uint64 amount) + { + increaseEnergy(user, amount); + } + + VOTTUNBRIDGE::transferToContract_output transferToContract( + const id& user, uint64 amount, uint64 orderId, uint64 invocationReward) + { + VOTTUNBRIDGE::transferToContract_input input{}; + VOTTUNBRIDGE::transferToContract_output output{}; + input.amount = amount; + input.orderId = orderId; + + this->invokeUserProcedure(VOTTUNBRIDGE_CONTRACT_INDEX, PROCEDURE_TRANSFER_TO_CONTRACT, + input, output, user, static_cast(invocationReward)); + return output; + } + + VOTTUNBRIDGE::createProposal_output createProposal( + const id& admin, uint8 proposalType, const id& target, const id& oldAddress, uint64 amount) + { + VOTTUNBRIDGE::createProposal_input input{}; + VOTTUNBRIDGE::createProposal_output output{}; + input.proposalType = proposalType; + input.targetAddress = target; + input.oldAddress = oldAddress; + input.amount = amount; + + this->invokeUserProcedure(VOTTUNBRIDGE_CONTRACT_INDEX, 6, input, output, admin, 0); + return output; + } + + VOTTUNBRIDGE::approveProposal_output approveProposal(const id& admin, uint64 proposalId) + { + VOTTUNBRIDGE::approveProposal_input input{}; + VOTTUNBRIDGE::approveProposal_output output{}; + input.proposalId = proposalId; + + this->invokeUserProcedure(VOTTUNBRIDGE_CONTRACT_INDEX, 7, input, output, admin, 0); + return output; + } + + VOTTUNBRIDGE::cancelProposal_output cancelProposal(const id& user, uint64 proposalId) + { + VOTTUNBRIDGE::cancelProposal_input input{}; + VOTTUNBRIDGE::cancelProposal_output output{}; + input.proposalId = proposalId; + + this->invokeUserProcedure(VOTTUNBRIDGE_CONTRACT_INDEX, 8, input, output, user, 0); + return output; + } + + VOTTUNBRIDGE::refundOrder_output refundOrder(const id& manager, uint64 orderId) + { + VOTTUNBRIDGE::refundOrder_input input{}; + VOTTUNBRIDGE::refundOrder_output output{}; + input.orderId = orderId; + + this->invokeUserProcedure(VOTTUNBRIDGE_CONTRACT_INDEX, 3, input, output, manager, 0); + return output; + } + + void callEndTick() + { + callSystemProcedure(VOTTUNBRIDGE_CONTRACT_INDEX, END_TICK); + } +}; + +TEST(VottunBridge, CreateOrder_RequiresFee) +{ + ContractTestingVottunBridge bridge; + const id user = id(1, 0, 0, 0); + const uint64 amount = 1000; + const uint64 fee = requiredFee(amount); + + std::cout << "[VottunBridge] CreateOrder_RequiresFee: amount=" << amount + << " fee=" << fee << " (sending fee-1)" << std::endl; + + increaseEnergy(user, fee - 1); + auto output = bridge.createOrder(user, amount, true, fee - 1); + EXPECT_EQ(output.status, static_cast(VOTTUNBRIDGE::EthBridgeError::insufficientTransactionFee)); +} + +TEST(VottunBridge, TransferToContract_RejectsMissingReward) +{ + ContractTestingVottunBridge bridge; + const id user = id(2, 0, 0, 0); + const uint64 amount = 200; + const uint64 fee = requiredFee(amount); + const id contractId = id(VOTTUNBRIDGE_CONTRACT_INDEX, 0, 0, 0); + + std::cout << "[VottunBridge] TransferToContract_RejectsMissingReward: amount=" << amount + << " fee=" << fee << " reward=0 contractBalanceSeed=1000" << std::endl; + + // Seed balances: user only has fees; contract already has balance > amount + increaseEnergy(user, fee); + increaseEnergy(contractId, 1000); + + auto orderOutput = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(orderOutput.status, 0); + + const uint64 lockedBefore = bridge.state()->lockedTokens; + const long long contractBalanceBefore = getBalance(contractId); + const long long userBalanceBefore = getBalance(user); + + auto transferOutput = bridge.transferToContract(user, amount, orderOutput.orderId, 0); + + EXPECT_EQ(transferOutput.status, static_cast(VOTTUNBRIDGE::EthBridgeError::invalidAmount)); + EXPECT_EQ(bridge.state()->lockedTokens, lockedBefore); + EXPECT_EQ(getBalance(contractId), contractBalanceBefore); + EXPECT_EQ(getBalance(user), userBalanceBefore); +} + +TEST(VottunBridge, TransferToContract_AcceptsExactReward) +{ + ContractTestingVottunBridge bridge; + const id user = id(3, 0, 0, 0); + const uint64 amount = 500; + const uint64 fee = requiredFee(amount); + const id contractId = id(VOTTUNBRIDGE_CONTRACT_INDEX, 0, 0, 0); + + std::cout << "[VottunBridge] TransferToContract_AcceptsExactReward: amount=" << amount + << " fee=" << fee << " reward=amount" << std::endl; + + increaseEnergy(user, fee + amount); + + auto orderOutput = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(orderOutput.status, 0); + + const uint64 lockedBefore = bridge.state()->lockedTokens; + const long long contractBalanceBefore = getBalance(contractId); + + auto transferOutput = bridge.transferToContract(user, amount, orderOutput.orderId, amount); + + EXPECT_EQ(transferOutput.status, 0); + EXPECT_EQ(bridge.state()->lockedTokens, lockedBefore + amount); + EXPECT_EQ(getBalance(contractId), contractBalanceBefore + amount); +} + +TEST(VottunBridge, TransferToContract_OrderNotFound) +{ + ContractTestingVottunBridge bridge; + const id user = id(5, 0, 0, 0); + const uint64 amount = 100; + + bridge.seedBalance(user, amount); + + auto output = bridge.transferToContract(user, amount, 9999, amount); + EXPECT_EQ(output.status, static_cast(VOTTUNBRIDGE::EthBridgeError::orderNotFound)); +} + +TEST(VottunBridge, TransferToContract_InvalidAmountMismatch) +{ + ContractTestingVottunBridge bridge; + const id user = id(6, 0, 0, 0); + const uint64 amount = 1000; // Must be >= minimumOrderAmount (200) + const uint64 fee = requiredFee(amount); + + bridge.seedBalance(user, fee + amount + 1); + + auto orderOutput = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(orderOutput.status, 0); + + auto output = bridge.transferToContract(user, amount + 1, orderOutput.orderId, amount + 1); + EXPECT_EQ(output.status, static_cast(VOTTUNBRIDGE::EthBridgeError::invalidAmount)); +} + +TEST(VottunBridge, TransferToContract_InvalidOrderState) +{ + ContractTestingVottunBridge bridge; + const id user = id(7, 0, 0, 0); + const uint64 amount = 1000; + const uint64 fee = requiredFee(amount); + + bridge.seedBalance(user, fee + amount); + + auto orderOutput = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(orderOutput.status, 0); + + VOTTUNBRIDGE::BridgeOrder order{}; + ASSERT_TRUE(bridge.findOrder(orderOutput.orderId, order)); + order.status = 1; // completed + ASSERT_TRUE(bridge.setOrderById(orderOutput.orderId, order)); + + auto output = bridge.transferToContract(user, amount, orderOutput.orderId, amount); + EXPECT_EQ(output.status, static_cast(VOTTUNBRIDGE::EthBridgeError::invalidOrderState)); +} + +TEST(VottunBridge, CreateOrder_CleansCompletedAndRefundedSlots) +{ + ContractTestingVottunBridge bridge; + const id user = id(4, 0, 0, 0); + const uint64 amount = 1000; + const uint64 fee = requiredFee(amount); + + VOTTUNBRIDGE::BridgeOrder filledOrder{}; + filledOrder.orderId = 1; + filledOrder.amount = amount; + filledOrder.status = 1; // completed + filledOrder.fromQubicToEthereum = true; + filledOrder.qubicSender = user; + + for (uint64 i = 0; i < bridge.state()->orders.capacity(); ++i) + { + filledOrder.orderId = i + 1; + filledOrder.status = (i % 2 == 0) ? 1 : 2; // completed/refunded + bridge.state()->orders.set(i, filledOrder); + } + + increaseEnergy(user, fee); + auto output = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(output.status, 0); + + VOTTUNBRIDGE::BridgeOrder createdOrder{}; + EXPECT_TRUE(bridge.findOrder(output.orderId, createdOrder)); + EXPECT_EQ(createdOrder.status, 0); + + // Single-pass recycling: the recyclable slot is directly overwritten + // with the new order (status=0), so no slots end up as 255. + // Verify that the number of completed/refunded orders decreased by 1 + // (one was recycled for the new order). + uint64 recycledCount = 0; + for (uint64 i = 0; i < bridge.state()->orders.capacity(); ++i) + { + uint8 s = bridge.state()->orders.get(i).status; + if (s == 1 || s == 2) + { + recycledCount++; + } + } + EXPECT_EQ(recycledCount, bridge.state()->orders.capacity() - 1); +} + +TEST(VottunBridge, CreateProposal_CleansExecutedProposalsWhenFull) +{ + ContractTestingVottunBridge bridge; + const id admin1 = id(10, 0, 0, 0); + const id admin2 = id(11, 0, 0, 0); + + bridge.state()->numberOfAdmins = 2; + bridge.state()->requiredApprovals = 2; + bridge.state()->admins.set(0, admin1); + bridge.state()->admins.set(1, admin2); + for (uint64 i = 2; i < bridge.state()->admins.capacity(); ++i) + { + bridge.state()->admins.set(i, NULL_ID); + } + + bridge.seedBalance(admin1, 1); + bridge.seedBalance(admin2, 1); + + VOTTUNBRIDGE::AdminProposal proposal{}; + proposal.approvalsCount = 1; + proposal.active = true; + proposal.executed = false; + for (uint64 i = 0; i < bridge.state()->proposals.capacity(); ++i) + { + proposal.proposalId = i + 1; + proposal.executed = (i % 2 == 0); + bridge.state()->proposals.set(i, proposal); + } + + auto output = bridge.createProposal(admin1, VOTTUNBRIDGE::PROPOSAL_CHANGE_THRESHOLD, + NULL_ID, NULL_ID, 2); + + EXPECT_EQ(output.status, 0); + + VOTTUNBRIDGE::AdminProposal createdProposal{}; + EXPECT_TRUE(bridge.findProposal(output.proposalId, createdProposal)); + EXPECT_TRUE(createdProposal.active); + EXPECT_FALSE(createdProposal.executed); + + // Single-pass recycling: the executed slot is cleared and immediately + // filled with the new proposal, so no slots end up fully empty. + // Verify that the number of executed proposals decreased by 1. + uint64 executedCount = 0; + for (uint64 i = 0; i < bridge.state()->proposals.capacity(); ++i) + { + VOTTUNBRIDGE::AdminProposal p = bridge.state()->proposals.get(i); + if (p.executed) + { + executedCount++; + } + } + // Originally half (16) were executed; one was recycled for the new proposal + EXPECT_EQ(executedCount, 15); +} + +TEST(VottunBridge, CreateProposal_InvalidTypeRejected) +{ + ContractTestingVottunBridge bridge; + const id admin1 = id(10, 0, 0, 0); + + bridge.state()->numberOfAdmins = 1; + bridge.state()->requiredApprovals = 1; + bridge.state()->admins.set(0, admin1); + bridge.seedBalance(admin1, 1); + + auto output = bridge.createProposal(admin1, 99, NULL_ID, NULL_ID, 0); + EXPECT_EQ(output.status, static_cast(VOTTUNBRIDGE::EthBridgeError::invalidAmount)); +} + +TEST(VottunBridge, ApproveProposal_NotOwnerRejected) +{ + ContractTestingVottunBridge bridge; + const id admin1 = id(10, 0, 0, 0); + const id admin2 = id(11, 0, 0, 0); + const id outsider = id(99, 0, 0, 0); + + bridge.state()->numberOfAdmins = 2; + bridge.state()->requiredApprovals = 2; + bridge.state()->admins.set(0, admin1); + bridge.state()->admins.set(1, admin2); + bridge.seedBalance(admin1, 1); + bridge.seedBalance(admin2, 1); + bridge.seedBalance(outsider, 1); + + auto proposalOutput = bridge.createProposal(admin1, VOTTUNBRIDGE::PROPOSAL_CHANGE_THRESHOLD, + NULL_ID, NULL_ID, 2); + EXPECT_EQ(proposalOutput.status, 0); + + auto approveOutput = bridge.approveProposal(outsider, proposalOutput.proposalId); + EXPECT_EQ(approveOutput.status, static_cast(VOTTUNBRIDGE::EthBridgeError::notOwner)); + EXPECT_FALSE(approveOutput.executed); +} + +TEST(VottunBridge, ApproveProposal_DoubleApprovalRejected) +{ + ContractTestingVottunBridge bridge; + const id admin1 = id(10, 0, 0, 0); + const id admin2 = id(11, 0, 0, 0); + + bridge.state()->numberOfAdmins = 2; + bridge.state()->requiredApprovals = 2; + bridge.state()->admins.set(0, admin1); + bridge.state()->admins.set(1, admin2); + bridge.seedBalance(admin1, 1); + bridge.seedBalance(admin2, 1); + + auto proposalOutput = bridge.createProposal(admin1, VOTTUNBRIDGE::PROPOSAL_CHANGE_THRESHOLD, + NULL_ID, NULL_ID, 2); + EXPECT_EQ(proposalOutput.status, 0); + + auto approveOutput = bridge.approveProposal(admin1, proposalOutput.proposalId); + EXPECT_EQ(approveOutput.status, static_cast(VOTTUNBRIDGE::EthBridgeError::proposalAlreadyApproved)); + EXPECT_FALSE(approveOutput.executed); +} + +TEST(VottunBridge, ApproveProposal_ExecutesChangeThreshold) +{ + ContractTestingVottunBridge bridge; + const id admin1 = id(10, 0, 0, 0); + const id admin2 = id(11, 0, 0, 0); + + bridge.state()->numberOfAdmins = 2; + bridge.state()->requiredApprovals = 2; + bridge.state()->admins.set(0, admin1); + bridge.state()->admins.set(1, admin2); + bridge.seedBalance(admin1, 1); + bridge.seedBalance(admin2, 1); + + auto proposalOutput = bridge.createProposal(admin1, VOTTUNBRIDGE::PROPOSAL_CHANGE_THRESHOLD, + NULL_ID, NULL_ID, 2); + EXPECT_EQ(proposalOutput.status, 0); + + auto approveOutput = bridge.approveProposal(admin2, proposalOutput.proposalId); + EXPECT_EQ(approveOutput.status, 0); + EXPECT_TRUE(approveOutput.executed); + EXPECT_EQ(bridge.state()->requiredApprovals, 2); +} + +TEST(VottunBridge, ApproveProposal_ProposalNotFound) +{ + ContractTestingVottunBridge bridge; + const id admin1 = id(12, 0, 0, 0); + + bridge.state()->numberOfAdmins = 1; + bridge.state()->requiredApprovals = 1; + bridge.state()->admins.set(0, admin1); + bridge.seedBalance(admin1, 1); + + auto output = bridge.approveProposal(admin1, 12345); + EXPECT_EQ(output.status, static_cast(VOTTUNBRIDGE::EthBridgeError::proposalNotFound)); + EXPECT_FALSE(output.executed); +} + +TEST(VottunBridge, ApproveProposal_AlreadyExecuted) +{ + ContractTestingVottunBridge bridge; + const id admin1 = id(13, 0, 0, 0); + const id admin2 = id(14, 0, 0, 0); + + bridge.state()->numberOfAdmins = 2; + bridge.state()->requiredApprovals = 2; + bridge.state()->admins.set(0, admin1); + bridge.state()->admins.set(1, admin2); + bridge.seedBalance(admin1, 1); + bridge.seedBalance(admin2, 1); + + auto proposalOutput = bridge.createProposal(admin1, VOTTUNBRIDGE::PROPOSAL_CHANGE_THRESHOLD, + NULL_ID, NULL_ID, 2); + EXPECT_EQ(proposalOutput.status, 0); + + auto approveOutput = bridge.approveProposal(admin2, proposalOutput.proposalId); + EXPECT_EQ(approveOutput.status, 0); + EXPECT_TRUE(approveOutput.executed); + + auto secondApprove = bridge.approveProposal(admin1, proposalOutput.proposalId); + EXPECT_EQ(secondApprove.status, static_cast(VOTTUNBRIDGE::EthBridgeError::proposalAlreadyExecuted)); + EXPECT_FALSE(secondApprove.executed); +} + +TEST(VottunBridge, TransferToContract_RefundsExcess) +{ + ContractTestingVottunBridge bridge; + const id user = id(20, 0, 0, 0); + const uint64 amount = 500; + const uint64 excess = 100; + const uint64 fee = requiredFee(amount); + const id contractId = id(VOTTUNBRIDGE_CONTRACT_INDEX, 0, 0, 0); + + std::cout << "[VottunBridge] TransferToContract_RefundsExcess: amount=" << amount + << " excess=" << excess << " fee=" << fee << std::endl; + + increaseEnergy(user, fee + amount + excess); + + auto orderOutput = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(orderOutput.status, 0); + + const uint64 lockedBefore = bridge.state()->lockedTokens; + const long long userBalanceBefore = getBalance(user); + + // Send more than required (amount + excess) + auto transferOutput = bridge.transferToContract(user, amount, orderOutput.orderId, amount + excess); + + EXPECT_EQ(transferOutput.status, 0); + // Should lock only the required amount + EXPECT_EQ(bridge.state()->lockedTokens, lockedBefore + amount); + // User should get excess back + EXPECT_EQ(getBalance(user), userBalanceBefore - amount); +} + +TEST(VottunBridge, TransferToContract_RefundsAllOnInsufficient) +{ + ContractTestingVottunBridge bridge; + const id user = id(21, 0, 0, 0); + const uint64 amount = 500; + const uint64 insufficientAmount = 200; + const uint64 fee = requiredFee(amount); + const id contractId = id(VOTTUNBRIDGE_CONTRACT_INDEX, 0, 0, 0); + + std::cout << "[VottunBridge] TransferToContract_RefundsAllOnInsufficient: amount=" << amount + << " sent=" << insufficientAmount << std::endl; + + increaseEnergy(user, fee + insufficientAmount); + + auto orderOutput = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(orderOutput.status, 0); + + const uint64 lockedBefore = bridge.state()->lockedTokens; + const long long userBalanceBefore = getBalance(user); + + // Send less than required + auto transferOutput = bridge.transferToContract(user, amount, orderOutput.orderId, insufficientAmount); + + EXPECT_EQ(transferOutput.status, static_cast(VOTTUNBRIDGE::EthBridgeError::invalidAmount)); + // Should NOT lock anything + EXPECT_EQ(bridge.state()->lockedTokens, lockedBefore); + // User should get everything back + EXPECT_EQ(getBalance(user), userBalanceBefore); +} + +TEST(VottunBridge, CancelProposal_Success) +{ + ContractTestingVottunBridge bridge; + const id admin1 = id(22, 0, 0, 0); + + bridge.state()->numberOfAdmins = 1; + bridge.state()->requiredApprovals = 1; + bridge.state()->admins.set(0, admin1); + bridge.seedBalance(admin1, 1); + + auto proposalOutput = bridge.createProposal(admin1, VOTTUNBRIDGE::PROPOSAL_CHANGE_THRESHOLD, + NULL_ID, NULL_ID, 2); + EXPECT_EQ(proposalOutput.status, 0); + + // Verify proposal is active + VOTTUNBRIDGE::AdminProposal proposal; + EXPECT_TRUE(bridge.findProposal(proposalOutput.proposalId, proposal)); + EXPECT_TRUE(proposal.active); + + // Cancel the proposal + auto cancelOutput = bridge.cancelProposal(admin1, proposalOutput.proposalId); + EXPECT_EQ(cancelOutput.status, 0); + + // Verify proposal is inactive + EXPECT_TRUE(bridge.findProposal(proposalOutput.proposalId, proposal)); + EXPECT_FALSE(proposal.active); +} + +TEST(VottunBridge, CancelProposal_NotCreatorRejected) +{ + ContractTestingVottunBridge bridge; + const id admin1 = id(23, 0, 0, 0); + const id admin2 = id(24, 0, 0, 0); + + bridge.state()->numberOfAdmins = 2; + bridge.state()->requiredApprovals = 2; + bridge.state()->admins.set(0, admin1); + bridge.state()->admins.set(1, admin2); + bridge.seedBalance(admin1, 1); + bridge.seedBalance(admin2, 1); + + // Admin1 creates proposal + auto proposalOutput = bridge.createProposal(admin1, VOTTUNBRIDGE::PROPOSAL_CHANGE_THRESHOLD, + NULL_ID, NULL_ID, 2); + EXPECT_EQ(proposalOutput.status, 0); + + // Admin2 tries to cancel (should fail - not the creator) + auto cancelOutput = bridge.cancelProposal(admin2, proposalOutput.proposalId); + EXPECT_EQ(cancelOutput.status, static_cast(VOTTUNBRIDGE::EthBridgeError::notAuthorized)); + + // Verify proposal is still active + VOTTUNBRIDGE::AdminProposal proposal; + EXPECT_TRUE(bridge.findProposal(proposalOutput.proposalId, proposal)); + EXPECT_TRUE(proposal.active); +} + +TEST(VottunBridge, CancelProposal_AlreadyExecutedRejected) +{ + ContractTestingVottunBridge bridge; + const id admin1 = id(25, 0, 0, 0); + const id admin2 = id(26, 0, 0, 0); + + bridge.state()->numberOfAdmins = 2; + bridge.state()->requiredApprovals = 2; + bridge.state()->admins.set(0, admin1); + bridge.state()->admins.set(1, admin2); + bridge.seedBalance(admin1, 1); + bridge.seedBalance(admin2, 1); + + auto proposalOutput = bridge.createProposal(admin1, VOTTUNBRIDGE::PROPOSAL_CHANGE_THRESHOLD, + NULL_ID, NULL_ID, 2); + EXPECT_EQ(proposalOutput.status, 0); + + // Execute the proposal by approving with a different admin (threshold is 2) + auto approveOutput = bridge.approveProposal(admin2, proposalOutput.proposalId); + EXPECT_EQ(approveOutput.status, 0); + EXPECT_TRUE(approveOutput.executed); + + // Ensure proposal is marked executed in state (explicit for this cancellation test) + VOTTUNBRIDGE::AdminProposal proposal; + ASSERT_TRUE(bridge.findProposal(proposalOutput.proposalId, proposal)); + proposal.executed = true; + ASSERT_TRUE(bridge.setProposalById(proposalOutput.proposalId, proposal)); + ASSERT_TRUE(bridge.findProposal(proposalOutput.proposalId, proposal)); + ASSERT_TRUE(proposal.executed); + + // Trying to cancel an executed proposal should fail + auto cancelOutput = bridge.cancelProposal(admin1, proposalOutput.proposalId); + EXPECT_EQ(cancelOutput.status, static_cast(VOTTUNBRIDGE::EthBridgeError::proposalAlreadyExecuted)); +} +// Additional tests for VottunBridge refund functionality with reserved fees +// Append these tests to contract_vottunbridge.cpp + +TEST(VottunBridge, RefundOrder_ReturnsFullAmountPlusFees) +{ + ContractTestingVottunBridge bridge; + const id user = id(100, 0, 0, 0); + const id manager = id(101, 0, 0, 0); + const uint64 amount = 10000; + const uint64 fee = requiredFee(amount); // 100 QU (50 + 50) + + std::cout << "[VottunBridge] RefundOrder_ReturnsFullAmountPlusFees: amount=" << amount + << " fee=" << fee << std::endl; + + // Setup: Add manager to managers array + bridge.state()->managers.set(0, manager); + bridge.seedBalance(manager, 1); // Ensure manager exists in spectrum + + // Give contract balance for refunds + const id contractId = id(VOTTUNBRIDGE_CONTRACT_INDEX, 0, 0, 0); + bridge.seedBalance(contractId, amount + fee); + + // User creates order and transfers tokens + bridge.seedBalance(user, fee + amount); + + const long long userBalanceBefore = getBalance(user); + + // Create order (user pays fees) + auto orderOutput = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(orderOutput.status, 0); + EXPECT_GT(orderOutput.orderId, 0); + + // Transfer tokens to contract + auto transferOutput = bridge.transferToContract(user, amount, orderOutput.orderId, amount); + EXPECT_EQ(transferOutput.status, 0); + + // Verify fees are reserved + EXPECT_EQ(bridge.state()->_reservedFees, 50); + EXPECT_EQ(bridge.state()->_reservedFeesQubic, 50); + + // Call END_TICK to simulate tick completion + bridge.callEndTick(); + + // Verify reserved fees were NOT distributed (still reserved for pending order) + EXPECT_EQ(bridge.state()->_reservedFees, 50); + EXPECT_EQ(bridge.state()->_reservedFeesQubic, 50); + + // Manager refunds the order + std::cout << " Contract balance BEFORE refund: " << getBalance(id(VOTTUNBRIDGE_CONTRACT_INDEX, 0, 0, 0)) << std::endl; + std::cout << " User balance BEFORE refund: " << getBalance(user) << std::endl; + + auto refundOutput = bridge.refundOrder(manager, orderOutput.orderId); + + std::cout << " Refund status: " << (int)refundOutput.status << std::endl; + std::cout << " Contract balance AFTER refund: " << getBalance(id(VOTTUNBRIDGE_CONTRACT_INDEX, 0, 0, 0)) << std::endl; + std::cout << " User balance AFTER refund: " << getBalance(user) << std::endl; + EXPECT_EQ(refundOutput.status, 0); + + // Verify order is refunded + VOTTUNBRIDGE::BridgeOrder order{}; + ASSERT_TRUE(bridge.findOrder(orderOutput.orderId, order)); + std::cout << " Order status after refund: " << (int)order.status << " (expected 2)" << std::endl; + std::cout << " Order tokensReceived: " << order.tokensReceived << std::endl; + std::cout << " Order tokensLocked: " << order.tokensLocked << std::endl; + std::cout << " lockedTokens state: " << bridge.state()->lockedTokens << std::endl; + EXPECT_EQ(order.status, 2); // Refunded + + // Verify fees are no longer reserved + EXPECT_EQ(bridge.state()->_reservedFees, 0); + EXPECT_EQ(bridge.state()->_reservedFeesQubic, 0); + + // Verify user received full refund: amount + both fees + const long long userBalanceAfter = getBalance(user); + EXPECT_EQ(userBalanceAfter, userBalanceBefore); // Back to original balance + + std::cout << " ✅ User balance: before=" << userBalanceBefore + << " after=" << userBalanceAfter + << " (full refund verified)" << std::endl; +} + +TEST(VottunBridge, RefundOrder_BeforeTransfer_ReturnsOnlyFees) +{ + ContractTestingVottunBridge bridge; + const id user = id(102, 0, 0, 0); + const id manager = id(103, 0, 0, 0); + const uint64 amount = 5000; + const uint64 fee = requiredFee(amount); // 50 QU (25 + 25) + + std::cout << "[VottunBridge] RefundOrder_BeforeTransfer_ReturnsOnlyFees: amount=" << amount + << " fee=" << fee << std::endl; + + // Setup: Add manager + bridge.state()->managers.set(0, manager); + bridge.seedBalance(manager, 1); // Ensure manager exists in spectrum + + // Give contract balance for refunds + const id contractId = id(VOTTUNBRIDGE_CONTRACT_INDEX, 0, 0, 0); + bridge.seedBalance(contractId, fee); + + // User creates order but does NOT transfer tokens + bridge.seedBalance(user, fee); + + const long long userBalanceBefore = getBalance(user); + + // Create order (user pays fees) + auto orderOutput = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(orderOutput.status, 0); + + // Verify fees are reserved + EXPECT_EQ(bridge.state()->_reservedFees, 25); + EXPECT_EQ(bridge.state()->_reservedFeesQubic, 25); + + const long long userBalanceAfterCreate = getBalance(user); + EXPECT_EQ(userBalanceAfterCreate, userBalanceBefore - fee); + + // Manager refunds the order (before transferToContract) + auto refundOutput = bridge.refundOrder(manager, orderOutput.orderId); + EXPECT_EQ(refundOutput.status, 0); + + // Verify user received fees back (no tokens to refund since they were never transferred) + const long long userBalanceAfter = getBalance(user); + EXPECT_EQ(userBalanceAfter, userBalanceBefore); // Back to original (fees refunded) + + std::cout << " ✅ User balance: before=" << userBalanceBefore + << " afterCreate=" << userBalanceAfterCreate + << " afterRefund=" << userBalanceAfter + << " (fees refunded)" << std::endl; +} + +TEST(VottunBridge, RefundOrder_AfterEndTick_StillRefundsFullAmount) +{ + ContractTestingVottunBridge bridge; + const id user = id(104, 0, 0, 0); + const id manager = id(105, 0, 0, 0); + const uint64 amount = 10000; + const uint64 fee = requiredFee(amount); + + std::cout << "[VottunBridge] RefundOrder_AfterEndTick_StillRefundsFullAmount" << std::endl; + + // Setup + bridge.state()->managers.set(0, manager); + bridge.seedBalance(manager, 1); // Ensure manager exists in spectrum + + // Give contract balance for refunds + const id contractId = id(VOTTUNBRIDGE_CONTRACT_INDEX, 0, 0, 0); + bridge.seedBalance(contractId, amount + fee); + + bridge.seedBalance(user, fee + amount); + + const long long userBalanceBefore = getBalance(user); + + // Create order and transfer + auto orderOutput = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(orderOutput.status, 0); + + auto transferOutput = bridge.transferToContract(user, amount, orderOutput.orderId, amount); + EXPECT_EQ(transferOutput.status, 0); + + // Simulate multiple ticks (fees should NOT be distributed while order is pending) + for (int i = 0; i < 5; i++) + { + bridge.callEndTick(); + } + + // Verify fees are STILL reserved (not distributed during END_TICK) + EXPECT_EQ(bridge.state()->_reservedFees, 50); + EXPECT_EQ(bridge.state()->_reservedFeesQubic, 50); + + // Refund after multiple ticks + auto refundOutput = bridge.refundOrder(manager, orderOutput.orderId); + EXPECT_EQ(refundOutput.status, 0); + + // User should still get full refund + const long long userBalanceAfter = getBalance(user); + EXPECT_EQ(userBalanceAfter, userBalanceBefore); + + std::cout << " ✅ Fees remained reserved through 5 ticks, full refund successful" << std::endl; +} + +TEST(VottunBridge, CreateOrder_ReservesFees) +{ + ContractTestingVottunBridge bridge; + const id user = id(106, 0, 0, 0); + const uint64 amount = 1000; + const uint64 fee = requiredFee(amount); // 10 QU (5 + 5) + + bridge.seedBalance(user, fee); + + // Initially, no fees are reserved + EXPECT_EQ(bridge.state()->_reservedFees, 0); + EXPECT_EQ(bridge.state()->_reservedFeesQubic, 0); + EXPECT_EQ(bridge.state()->_earnedFees, 0); + EXPECT_EQ(bridge.state()->_earnedFeesQubic, 0); + + // Create order + auto orderOutput = bridge.createOrder(user, amount, true, fee); + EXPECT_EQ(orderOutput.status, 0); + + // Verify fees are both earned AND reserved + EXPECT_EQ(bridge.state()->_earnedFees, 5); + EXPECT_EQ(bridge.state()->_earnedFeesQubic, 5); + EXPECT_EQ(bridge.state()->_reservedFees, 5); + EXPECT_EQ(bridge.state()->_reservedFeesQubic, 5); +} + +TEST(VottunBridge, CompleteOrder_ReleasesReservedFees) +{ + ContractTestingVottunBridge bridge; + const id user = id(107, 0, 0, 0); + const id manager = id(108, 0, 0, 0); + const uint64 amount = 1000; + const uint64 fee = requiredFee(amount); + + // Setup + bridge.state()->managers.set(0, manager); + bridge.seedBalance(manager, 1); // Ensure manager exists in spectrum + bridge.state()->lockedTokens = 10000; // Ensure enough liquidity for EVM->Qubic + const id contractId = id(VOTTUNBRIDGE_CONTRACT_INDEX, 0, 0, 0); + bridge.seedBalance(contractId, amount); // Ensure contract can transfer to user + bridge.seedBalance(user, fee); + + // Create order (EVM->Qubic direction, fromQubicToEthereum=false) + auto orderOutput = bridge.createOrder(user, amount, false, fee); + EXPECT_EQ(orderOutput.status, 0); + + // Verify fees are reserved + EXPECT_EQ(bridge.state()->_reservedFees, 5); + EXPECT_EQ(bridge.state()->_reservedFeesQubic, 5); + + // Manager completes the order + VOTTUNBRIDGE::completeOrder_input input{}; + VOTTUNBRIDGE::completeOrder_output output{}; + input.orderId = orderOutput.orderId; + + bridge.invokeUserProcedure(VOTTUNBRIDGE_CONTRACT_INDEX, 2, input, output, manager, 0); + EXPECT_EQ(output.status, 0); + + // Verify reserved fees are released (can now be distributed) + EXPECT_EQ(bridge.state()->_reservedFees, 0); + EXPECT_EQ(bridge.state()->_reservedFeesQubic, 0); + + // Earned fees remain (not distributed yet) + EXPECT_EQ(bridge.state()->_earnedFees, 5); + EXPECT_EQ(bridge.state()->_earnedFeesQubic, 5); +} diff --git a/test/test.vcxproj b/test/test.vcxproj index b88db9fcf..456481944 100644 --- a/test/test.vcxproj +++ b/test/test.vcxproj @@ -146,6 +146,7 @@ + diff --git a/test/test.vcxproj.filters b/test/test.vcxproj.filters index 589346059..c105bdb5d 100644 --- a/test/test.vcxproj.filters +++ b/test/test.vcxproj.filters @@ -41,6 +41,7 @@ + From 444d6babd6000eddcb87dc5f7227f752c901a49d Mon Sep 17 00:00:00 2001 From: fnordspace Date: Mon, 16 Mar 2026 15:24:15 +0100 Subject: [PATCH 06/15] Add NO_VOTTUN toggle --- src/contract_core/contract_def.h | 6 ++++++ src/qubic.cpp | 2 ++ 2 files changed, 8 insertions(+) diff --git a/src/contract_core/contract_def.h b/src/contract_core/contract_def.h index 550eb70fc..f1f5bf2a4 100644 --- a/src/contract_core/contract_def.h +++ b/src/contract_core/contract_def.h @@ -254,6 +254,8 @@ #define CONTRACT_STATE2_TYPE PULSE2 #include "contracts/Pulse.h" +#ifndef NO_VOTTUN + #undef CONTRACT_INDEX #undef CONTRACT_STATE_TYPE #undef CONTRACT_STATE2_TYPE @@ -264,6 +266,8 @@ #define CONTRACT_STATE2_TYPE VOTTUNBRIDGE2 #include "contracts/VottunBridge.h" +#endif + // new contracts should be added above this line #ifdef INCLUDE_CONTRACT_TEST_EXAMPLES @@ -374,7 +378,9 @@ constexpr struct ContractDescription {"QTF", 199, 10000, sizeof(QTF::StateData)}, // proposal in epoch 197, IPO in 198, construction and first use in 199 {"QDUEL", 199, 10000, sizeof(QDUEL::StateData)}, // proposal in epoch 197, IPO in 198, construction and first use in 199 {"PULSE", 204, 10000, sizeof(PULSE::StateData)}, // proposal in epoch 202, IPO in 203, construction and first use in 204 +#ifndef NO_VOTTUN {"VOTTUN", 205, 10000, sizeof(VOTTUNBRIDGE::StateData)}, // proposal in epoch 204, IPO in 205, construction and first use in 205 +#endif // new contracts should be added above this line #ifdef INCLUDE_CONTRACT_TEST_EXAMPLES {"TESTEXA", 138, 10000, sizeof(TESTEXA::StateData)}, diff --git a/src/qubic.cpp b/src/qubic.cpp index 402be3668..558e6f01b 100644 --- a/src/qubic.cpp +++ b/src/qubic.cpp @@ -1,5 +1,7 @@ #define SINGLE_COMPILE_UNIT +// #define NO_VOTTUN + //#define INCLUDE_CONTRACT_TEST_EXAMPLES // contract_def.h needs to be included first to make sure that contracts have minimal access From d7ecc6818b6221486effd0ce4f7b624293a3a4bb Mon Sep 17 00:00:00 2001 From: fnordspace Date: Mon, 16 Mar 2026 15:45:27 +0100 Subject: [PATCH 07/15] Adjust `TICK_DURATION_FOR_ALLOCATION_MS` and `TRANSACTION_SPARSENESS` --- src/public_settings.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/public_settings.h b/src/public_settings.h index b4d1c0542..2117f9c0e 100644 --- a/src/public_settings.h +++ b/src/public_settings.h @@ -30,8 +30,8 @@ // The tick duration used to calculate the size of memory buffers. // This determines the memory footprint of the application. -#define TICK_DURATION_FOR_ALLOCATION_MS 750 -#define TRANSACTION_SPARSENESS 1 +#define TICK_DURATION_FOR_ALLOCATION_MS 350 +#define TRANSACTION_SPARSENESS 3 // Number of ticks that are stored in the pending txs pool. This also defines how many ticks in advance a tx can be registered. #define PENDING_TXS_POOL_NUM_TICKS (1000 * 60 * 10ULL / TICK_DURATION_FOR_ALLOCATION_MS) // 10 minutes From 8558f5b59d0dede0c0e81361c0e8cc66ad4a0132 Mon Sep 17 00:00:00 2001 From: Philipp Werner <22914157+philippwerner@users.noreply.github.com> Date: Mon, 16 Mar 2026 15:57:15 +0100 Subject: [PATCH 08/15] Fix asset iteration after snapshot loading (#795) * Fix asset iteration after snapshot loading Rebuilding the index lists changes the order of asset iteration. So rebuilding may lead to misalignment after loading a snapshot. As a solution, the asset index lists are saved in the snapshot and loaded from a file instead of being rebuilt. Rebuilding still happens at the end of the epoch and when the node is started from scratch. * Fix missing return --- src/assets/assets.h | 34 ++++++++++++++++++++++++++++++++-- src/qubic.cpp | 8 +++++++- 2 files changed, 39 insertions(+), 3 deletions(-) diff --git a/src/assets/assets.h b/src/assets/assets.h index 5a5adff22..f6f72e019 100644 --- a/src/assets/assets.h +++ b/src/assets/assets.h @@ -14,6 +14,7 @@ #include "contract_core/contract_def.h" #include "public_settings.h" +#include "private_settings.h" #include "logging/logging.h" #include "kangaroo_twelve.h" #include "four_q.h" @@ -771,7 +772,7 @@ static bool saveUniverse(const CHAR16* fileName = UNIVERSE_FILE_NAME, const CHAR return false; } -static bool loadUniverse(const CHAR16* fileName = UNIVERSE_FILE_NAME, CHAR16* directory = NULL) +static bool loadUniverse(const CHAR16* fileName = UNIVERSE_FILE_NAME, CHAR16* directory = NULL, bool rebuildIndexLists = true) { PROFILE_SCOPE(); @@ -782,9 +783,38 @@ static bool loadUniverse(const CHAR16* fileName = UNIVERSE_FILE_NAME, CHAR16* di return false; } - as.indexLists.rebuild(); + + if (rebuildIndexLists) + as.indexLists.rebuild(); + + return true; +} + +#if TICK_STORAGE_AUTOSAVE_MODE +static bool saveSnapshotUniverseIndex(const CHAR16* fileName, const CHAR16* directory = NULL) +{ + long long savedSize = save(fileName, sizeof(as.indexLists), (unsigned char*)&as.indexLists, directory); + logToConsole(L"Saving universe index"); + if (savedSize != sizeof(as.indexLists)) + { + logToConsole(L"Failed to save universe index"); + return false; + } + return true; +} + +static bool loadSnapshotUniverseIndex(const CHAR16* fileName, CHAR16* directory = NULL) +{ + long long loadedSize = load(fileName, sizeof(as.indexLists), (unsigned char*)&as.indexLists, directory); + logToConsole(L"Loading universe index"); + if (loadedSize != sizeof(as.indexLists)) + { + logToConsole(L"Failed to load universe index"); + return false; + } return true; } +#endif static void assetsEndEpoch() { diff --git a/src/qubic.cpp b/src/qubic.cpp index 558e6f01b..1ae1cace8 100644 --- a/src/qubic.cpp +++ b/src/qubic.cpp @@ -4336,6 +4336,8 @@ static bool saveAllNodeStates() logToConsole(L"Failed to save universe"); return false; } + if (!saveSnapshotUniverseIndex(L"snapshotUniverseIndex", directory)) + return false; CONTRACT_FILE_NAME[sizeof(CONTRACT_FILE_NAME) / sizeof(CONTRACT_FILE_NAME[0]) - 4] = L'0'; CONTRACT_FILE_NAME[sizeof(CONTRACT_FILE_NAME) / sizeof(CONTRACT_FILE_NAME[0]) - 3] = L'0'; @@ -4505,14 +4507,18 @@ static bool loadAllNodeStates() return false; } + // When loading from a snapshot, the universe index lists must not be rebuilt, because this may change the + // order of asset iteration and lead to misalignment. Instead, the original index must be saved/loaded. UNIVERSE_FILE_NAME[sizeof(UNIVERSE_FILE_NAME) / sizeof(UNIVERSE_FILE_NAME[0]) - 4] = L'0'; UNIVERSE_FILE_NAME[sizeof(UNIVERSE_FILE_NAME) / sizeof(UNIVERSE_FILE_NAME[0]) - 3] = L'0'; UNIVERSE_FILE_NAME[sizeof(UNIVERSE_FILE_NAME) / sizeof(UNIVERSE_FILE_NAME[0]) - 2] = L'0'; - if (!loadUniverse(UNIVERSE_FILE_NAME, directory)) + if (!loadUniverse(UNIVERSE_FILE_NAME, directory, /*rebuildIndexLists=*/false)) { logToConsole(L"Failed to load universe"); return false; } + if (!loadSnapshotUniverseIndex(L"snapshotUniverseIndex", directory)) + return false; CONTRACT_FILE_NAME[sizeof(CONTRACT_FILE_NAME) / sizeof(CONTRACT_FILE_NAME[0]) - 4] = L'0'; CONTRACT_FILE_NAME[sizeof(CONTRACT_FILE_NAME) / sizeof(CONTRACT_FILE_NAME[0]) - 3] = L'0'; From 946f49cae0d75e38a940e3f5a950c39f3650e5f1 Mon Sep 17 00:00:00 2001 From: fnordspace Date: Mon, 16 Mar 2026 16:03:56 +0100 Subject: [PATCH 09/15] update params for epoch 205 / v1.283.0 --- src/public_settings.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/public_settings.h b/src/public_settings.h index 2117f9c0e..ac90b6e9f 100644 --- a/src/public_settings.h +++ b/src/public_settings.h @@ -66,12 +66,12 @@ static_assert(AUTO_FORCE_NEXT_TICK_THRESHOLD* TARGET_TICK_DURATION >= PEER_REFRE // Config options that should NOT be changed by operators #define VERSION_A 1 -#define VERSION_B 282 +#define VERSION_B 283 #define VERSION_C 0 // Epoch and initial tick for node startup -#define EPOCH 204 -#define TICK 45693000 +#define EPOCH 205 +#define TICK 46460000 #define TICK_IS_FIRST_TICK_OF_EPOCH 1 // Set to 0 if the network is restarted during the EPOCH with a new initial TICK #define ARBITRATOR "AFZPUAIYVPNUYGJRQVLUKOPPVLHAZQTGLYAAUUNBXFTVTAMSBKQBLEIEPCVJ" From 79d0a6a06a6f0383ac8a7d8117a423a20bdbbcc5 Mon Sep 17 00:00:00 2001 From: cyber-pc Date: Tue, 17 Mar 2026 07:52:16 +0700 Subject: [PATCH 10/15] Increase ADDITION_SOLUTION_THRESHOLD_DEFAULT to 74800 --- src/public_settings.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/public_settings.h b/src/public_settings.h index ac90b6e9f..22eaa320c 100644 --- a/src/public_settings.h +++ b/src/public_settings.h @@ -103,7 +103,7 @@ static constexpr unsigned long long ADDITION_NUMBER_OF_TICKS = 1000; static constexpr unsigned long long ADDITION_NUMBER_OF_NEIGHBORS = 728; // 2M. Must be divided by 2 static constexpr unsigned long long ADDITION_NUMBER_OF_MUTATIONS = 300; static constexpr unsigned long long ADDITION_POPULATION_THRESHOLD = ADDITION_NUMBER_OF_INPUT_NEURONS + ADDITION_NUMBER_OF_OUTPUT_NEURONS + ADDITION_NUMBER_OF_MUTATIONS; // P -static constexpr unsigned int ADDITION_SOLUTION_THRESHOLD_DEFAULT = 74500; +static constexpr unsigned int ADDITION_SOLUTION_THRESHOLD_DEFAULT = 74800; // Multipler of score static constexpr unsigned int HYPERIDENTITY_SOLUTION_MULTIPLER = 1; From 510650d88cf5705883b849e6dbff470b5a24bcba Mon Sep 17 00:00:00 2001 From: Philipp Werner <22914157+philippwerner@users.noreply.github.com> Date: Tue, 17 Mar 2026 10:33:37 +0100 Subject: [PATCH 11/15] Fix incomplete NO_VOTTUN toggle --- src/contract_core/contract_def.h | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/contract_core/contract_def.h b/src/contract_core/contract_def.h index f1f5bf2a4..1b20d02fd 100644 --- a/src/contract_core/contract_def.h +++ b/src/contract_core/contract_def.h @@ -501,7 +501,9 @@ static void initializeContracts() REGISTER_CONTRACT_FUNCTIONS_AND_PROCEDURES(QTF); REGISTER_CONTRACT_FUNCTIONS_AND_PROCEDURES(QDUEL); REGISTER_CONTRACT_FUNCTIONS_AND_PROCEDURES(PULSE); +#ifndef NO_VOTTUN REGISTER_CONTRACT_FUNCTIONS_AND_PROCEDURES(VOTTUNBRIDGE); +#endif // new contracts should be added above this line #ifdef INCLUDE_CONTRACT_TEST_EXAMPLES REGISTER_CONTRACT_FUNCTIONS_AND_PROCEDURES(TESTEXA); From 26672821687097e5c5e8a09172470e4aee3fef3a Mon Sep 17 00:00:00 2001 From: fnordspace Date: Tue, 17 Mar 2026 10:38:44 +0100 Subject: [PATCH 12/15] Fix construction epoch for Vottun --- src/contract_core/contract_def.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/contract_core/contract_def.h b/src/contract_core/contract_def.h index 1b20d02fd..095bf89a1 100644 --- a/src/contract_core/contract_def.h +++ b/src/contract_core/contract_def.h @@ -379,7 +379,7 @@ constexpr struct ContractDescription {"QDUEL", 199, 10000, sizeof(QDUEL::StateData)}, // proposal in epoch 197, IPO in 198, construction and first use in 199 {"PULSE", 204, 10000, sizeof(PULSE::StateData)}, // proposal in epoch 202, IPO in 203, construction and first use in 204 #ifndef NO_VOTTUN - {"VOTTUN", 205, 10000, sizeof(VOTTUNBRIDGE::StateData)}, // proposal in epoch 204, IPO in 205, construction and first use in 205 + {"VOTTUN", 206, 10000, sizeof(VOTTUNBRIDGE::StateData)}, // proposal in epoch 204, IPO in 205, construction and first use in 206 #endif // new contracts should be added above this line #ifdef INCLUDE_CONTRACT_TEST_EXAMPLES From 2c6c01663147e1dea212f47a67c6af4a958e8a71 Mon Sep 17 00:00:00 2001 From: J0ET0M <107187448+J0ET0M@users.noreply.github.com> Date: Tue, 17 Mar 2026 17:57:06 +0100 Subject: [PATCH 13/15] add broadcast_custom_mining task/sol placeholders (#797) --- src/network_messages/network_message_type.h | 2 + src/qubic.cpp | 65 ++++++++++++++++++++- 2 files changed, 66 insertions(+), 1 deletion(-) diff --git a/src/network_messages/network_message_type.h b/src/network_messages/network_message_type.h index 7ec9a6af7..bf7d424db 100644 --- a/src/network_messages/network_message_type.h +++ b/src/network_messages/network_message_type.h @@ -51,6 +51,8 @@ enum NetworkMessageType : unsigned char RESPOND_ACTIVE_IPO = 65, REQUEST_ORACLE_DATA = 66, RESPOND_ORACLE_DATA = 67, + BROADCAST_CUSTOM_MINING_TASK = 68, + BROADCAST_CUSTOM_MINING_SOLUTION = 69, ORACLE_MACHINE_QUERY = 190, // only on communication channel Core node <-> OM node ORACLE_MACHINE_REPLY = 191, // only on communication channel Core node <-> OM node REQUEST_TX_STATUS = 201, // tx addon only diff --git a/src/qubic.cpp b/src/qubic.cpp index 1ae1cace8..3121d484e 100644 --- a/src/qubic.cpp +++ b/src/qubic.cpp @@ -1477,10 +1477,61 @@ static void processRequestedCustomMiningSolutionVerificationRequest(Peer* peer, } } +// Hardcoded doge dispatcher public key (identity: XPILPIJYHRBTACMMIRSJLIZWCXDBHWVEOTZBQFBXWEUXDZGGDEKDQPIEQKQK) +static const unsigned char dogeDispatcherPubkey[32] = { + 0x25, 0x98, 0x6d, 0x38, 0xa6, 0x3d, 0xd6, 0x45, + 0x0c, 0x07, 0x34, 0xd8, 0xaa, 0x47, 0x95, 0x27, + 0xd7, 0x2c, 0x0f, 0x9b, 0x3a, 0x86, 0x0a, 0xa8, + 0x9e, 0x9f, 0xb1, 0xf3, 0xfd, 0x3d, 0x1f, 0x95 +}; + +// Process a doge custom mining task broadcast (type 68). +// Verifies the signature against the hardcoded doge dispatcher public key and relays if valid. +static void processBroadcastCustomMiningTask(RequestResponseHeader* header) +{ + if (!header->isDejavuZero()) + return; + const unsigned int messageSize = header->size() - sizeof(RequestResponseHeader); + if (messageSize <= SIGNATURE_SIZE) + return; + const unsigned char* payload = (const unsigned char*)header->getPayload(); + m256i digest; + KangarooTwelve(payload, messageSize - SIGNATURE_SIZE, &digest, sizeof(digest)); + if (verify(dogeDispatcherPubkey, digest.m256i_u8, payload + (messageSize - SIGNATURE_SIZE))) + { + enqueueResponse(NULL, header); + } +} + +// Process a doge custom mining solution broadcast (type 69). +// Verifies the signature against the sender's public key (first 32 bytes of payload) +// and relays if the sender is a computor or has enough balance. +static void processBroadcastCustomMiningSolution(RequestResponseHeader* header) +{ + if (!header->isDejavuZero()) + return; + const unsigned int messageSize = header->size() - sizeof(RequestResponseHeader); + if (messageSize <= SIGNATURE_SIZE) + return; + const unsigned char* payload = (const unsigned char*)header->getPayload(); + const m256i* sourcePublicKey = (const m256i*)payload; + + m256i digest; + KangarooTwelve(payload, messageSize - SIGNATURE_SIZE, &digest, sizeof(digest)); + if (verify(sourcePublicKey->m256i_u8, digest.m256i_u8, payload + (messageSize - SIGNATURE_SIZE))) + { + if (computorIndex(*sourcePublicKey) >= 0 + || (::spectrumIndex(*sourcePublicKey) >= 0 && energy(::spectrumIndex(*sourcePublicKey)) >= MESSAGE_DISSEMINATION_THRESHOLD)) + { + enqueueResponse(NULL, header); + } + } +} + // Process custom mining data requests. // Currently supports: // - Requesting a range of tasks (using Unix timestamps as unique indexes; each task has only one unique index). -// - Requesting all solutions corresponding to a specific task index. +// - Requesting all solutions corresponding to a specific task index. // The total size of the response will not exceed CUSTOM_MINING_RESPOND_MESSAGE_MAX_SIZE. // For the solution respond, only respond solution that has not been verified yet static void processCustomMiningDataRequest(Peer* peer, const unsigned long long processorNumber, RequestResponseHeader* header) @@ -2286,6 +2337,18 @@ static void requestProcessor(void* ProcedureArgument) } break; + case BROADCAST_CUSTOM_MINING_TASK: + { + processBroadcastCustomMiningTask(header); + } + break; + + case BROADCAST_CUSTOM_MINING_SOLUTION: + { + processBroadcastCustomMiningSolution(header); + } + break; + case RequestCustomMiningSolutionVerification::type(): { processRequestedCustomMiningSolutionVerificationRequest(peer, header); From cb53c84377c69bdfe74abe76ef108a77bae19b28 Mon Sep 17 00:00:00 2001 From: Philipp Werner <22914157+philippwerner@users.noreply.github.com> Date: Tue, 17 Mar 2026 20:05:07 +0100 Subject: [PATCH 14/15] Oracle documentation (#796) * Add oracle docs * Improve oracle docs in the code (comments) * Address comments of fnordspace --- README.md | 1 + doc/OracleEngine.png | Bin 0 -> 88714 bytes doc/OracleEngine.svg | 3 + doc/contracts.md | 6 + doc/contracts_oracles.md | 484 ++++++++++++++++++++++++ src/assets/net_msg_impl.h | 6 +- src/contracts/qpi.h | 35 +- src/network_messages/common_def.h | 2 +- src/oracle_core/oracle_interfaces_def.h | 4 + src/oracle_interfaces/Price.h | 4 +- src/private_settings.h | 2 + src/qubic.cpp | 2 +- 12 files changed, 528 insertions(+), 21 deletions(-) create mode 100644 doc/OracleEngine.png create mode 100644 doc/OracleEngine.svg create mode 100644 doc/contracts_oracles.md diff --git a/README.md b/README.md index 8d3a3bcaa..0a31460cd 100644 --- a/README.md +++ b/README.md @@ -150,5 +150,6 @@ We cannot support you in any case. You are welcome to provide updates, bug fixes - [Qubic protocol](doc/protocol.md) - [Custom mining](doc/custom_mining.md) - [Seamless epoch transition](SEAMLESS.md) +- [Querying oracles](doc/contracts_oracles.md) - [Proposals and voting](doc/contracts_proposals.md) diff --git a/doc/OracleEngine.png b/doc/OracleEngine.png new file mode 100644 index 0000000000000000000000000000000000000000..f646ace4e5c6cf1bd574d4c4aaf69621f6db9476 GIT binary patch literal 88714 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 + +
oe.startContractQuery(), oe.startUserQuery(), or oe.generateSubscriptionQueries()
oe.startContractQuery(), oe.start...
oe.processOracleMachineReply()
oe.processOracleMachineReply()
OM Node
OM Node
request processor
request pr...
tick / contract processor
tick / contract proc...
oe.getReplyCommitTransaction()
oe.getReplyCommitTransaction()
OracleMachineQuery message
OracleMachineQuery message
OracleMachineReply message
OracleMachineReply message
broadcast reply commit transaction per computor
broadcast reply commit transaction per comput...
Other Core Nodes
Other Core No...
processTick()
processTick()
processTick()
processTick()
oe.processOracleReplyCommitTransaction():

When a quorum of commits is reached, status
is changed from pending to committed and it is time to reveal the oracle reply.
oe.processOracleReplyCommitTransaction():...
oe.getReplyCommitTransaction()
oe.getReplyCommitTransaction()
broadcast transaction per computor
broadcast transaction per computor
broadcast reply reveal transaction
broadcast reply reveal transaction
Other Core Nodes
Other Core No...
oe.getReplyRevealTransaction()
oe.getReplyRevealTransaction()
Another node may broadcast a reveal transaction concurrently, but the first reveal received stops the node from sending an own reveal through oe.announceExpectedRevealTransaction()
Another node may broadcast a reveal transaction...
processTick()
processTick()
oe.processOracleReplyRevealTransaction():

Knowledge proofs are checked and commits may be invalidated, oracle revenue points are granted, status is set to success (or unresolvable if too many commits were invalidated)
oe.processOracleReplyRevealTransaction():...
oe.getNotification()

... returns contract notifications that are run in the contract processor one after another.
oe.getNotification()...
processTick()
processTick()
oe.processTimeouts():

... checks for timeouts in every tick; updates state to timeout and queues notification if timeout is hit
oe.processTimeouts():...
oe.getNotification()

... returns contract notifications that are run in the contract processor one after another.
oe.getNotification()...
Oracle Engine's most important functions and interactions for processing queries
(oe = oracleEngine)
Oracle Engine's most important functions and interactions for processing que... \ No newline at end of file diff --git a/doc/contracts.md b/doc/contracts.md index 52f1e21a8..318d1e932 100644 --- a/doc/contracts.md +++ b/doc/contracts.md @@ -478,6 +478,12 @@ QX never releases shares passively (following call of `qpi.acquireShares()` by a The callbacks `PRE_RELEASE_SHARES()` and `PRE_ACQUIRE_SHARES()` may also check that the `qpi.originator()` initiating the transfer is the owner/possessor. +## Querying off-chain data from Oracles + +Oracles enable Smart Contracts to actively query off-chain data sources called Oracles. +Read [Querying Oracles from Contracts](contracts_oracles.md) for more details. + + ## Other QPI features ### Container types diff --git a/doc/contracts_oracles.md b/doc/contracts_oracles.md new file mode 100644 index 000000000..c886f1b5c --- /dev/null +++ b/doc/contracts_oracles.md @@ -0,0 +1,484 @@ +# Querying oracles from contracts + +Oracles enable Smart Contracts to actively query off-chain data sources via the QPI. +When a query is initiated, the Core nodes, which run the contracts, communicate with the Oracle Machine (OM) nodes, which serve as a bridge between the Core nodes and the Oracles. +Oracles are the sources from which information can be retrieved. +They are usually independent from Qubic. +Oracles provide the queried information to the OM nodes, which send a reply back to the Core nodes. +Afterwards, the reply needs to be confirmed by the Quorum, before it is made available on-chain. + +Queries to Oracles are subject to fees to avoid spam. +Those fees are destroyed (not put into execution reserve as with regular burning of QU). + +The OM nodes are run by computor operators, as the Core nodes. +The participation in replying to Oracle Queries is reflected in an additional component of the computors revenue algorithm, similar to transaction counting. + + +## Query lifecycle and status + +When a query is initiated, the following happens: + +1. The fee is deduced and destroyed (if an error occurs during the start of the query, the fee is reimbursed), +2. A query ID is generated that allows to track the query, +3. The query status is set to `ORACLE_QUERY_STATUS_PENDING`, +4. The query is sent to the Oracle Machine nodes. + +Afterwards, the execution (of contract code and transactions) continues. +That is, the Oracle Machine nodes process the query asynchronously. +They usually request the information from the Oracle, an external information provider, and send the reply back to the core node. +They may also get the Oracle Reply from their cache if it is already available from a prior request. + +After receiving the reply, the core nodes create one reply commit transaction per computor (whereas each transaction may contain reply commits of multiple queries for increasing efficiency). +The commits consist of a digest and a knowledge proof of the Oracle Reply, but do not reveal the actual value of the Oracle Reply yet. +When 451 agreeing reply commits have been processed, the status of the query switches to `ORACLE_QUERY_STATUS_COMMITTED`. +After that, the fastest computors send a reply reveal transaction, which changes the status to `ORACLE_QUERY_STATUS_SUCCESS` and triggers the notification when executed. + +As an incentive for providing fast and correct Oracle Replies, there is an oracle revenue counter for each computor, which influences the overall revenue payed to the computor at the end of the epoch. +Revenue points are granted to the first 451 reply commits (+ the ones in the same tick) with agreeing digest and correct knowledge proof when processing the reply reveal transaction. + +If too many commits disagree in the digest or have wrong knowledge proof, a quorum of reply commits isn't possible anymore. +In this case, the status changes to `ORACLE_QUERY_STATUS_UNRESOLVABLE` and error notification without a valid reply is triggered immediately. + +Each query is associated with a timeout in order to handle the lack of a timely reply, a quorum of commits, and/or a reveal. +When the timeout hits, the status switches to `ORACLE_QUERY_STATUS_TIMEOUT` and error notification is triggered. + +All queries and replies stay available until the end of the epoch via their unique query ID. + + +## Query types + +For contracts, there are two ways of querying Oracles: + +1. One-time queries, the normal way of querying an oracle. Each of these queries is completely independent. +2. Subscriptions, a cheaper and more efficient way to query time-dependent information, such as prices, regularly. A subscription repeatedly sends the same query, only changing the query timestamp. The subscription queries may be shared by multiple contracts automatically. + +Further, a one-time query can also be started by a user through a special transaction. + +Here is an overview of the three types: + +| | One-time contract query | Subscription contract query | One-time user query | +|--|--|--|--| +| Start | QPI call `QUERY_ORACLE` | QPI call `SUBSCRIBE_ORACLE` / scheduler | Special transaction to zero address (`OracleUserQueryTransaction`) | +| Fee | Per query (`QUERY_ORACLE`) | Per subscription (`SUBSCRIBE_ORACLE`), cheaper than many equivalent one-time queries | Per query (`OracleUserQueryTransaction`) | +| Notification | User procedure | User procedure | - | +| Timing | Minimal latency | Potentially synced with other contracts for maximal efficiency | Minimal latency | + + +## Oracle interfaces + +An oracle interface defines the Oracle Machine input and output types: `OracleQuery` and `OracleReply`. +Multiple oracles (sources of information) may share the same input and output structs, making them accessible through the same interface. +Multiple oracle interfaces usually differ in their definition of `OracleQuery` and `OracleReply`, because they provide different types of information and require different parameter for querying the information. + +An example interface is `Price`, providing access to crypto prices of multiple exchanges (oracles). +Future interfaces, that have not been implemented yet may be: `SportEvent`, `YesNoResult`, `IntResult`. +The source code of the oracles interfaces resides in the directory `src/oracle_interfaces/` of the Qubic Core repository, with one header file per oracle interface. + +In the Qubic contracts, oracle interfaces are made available through the namespace `OI`. +For example, you can access the oracle query struct type of the `Price` interface via `OI::Price::OracleQuery`. + + +### Oracle query + +The `OracleQuery` struct of the interface defines the input of the Oracle Machine, specifying what exactly is queried. +For example, the `OracleQuery` struct of the `Price` interface has the following member variables: +- `oracle`: the Oracle to ask for (e.g., binance, mexc, gate.io), +- `timestamp`: the specific date and time to ask the price for, +- `currency1` and `currency2`: the currency pair to get the price for. + +In general, the `OracleQuery` struct must be designed in a way that consecutive queries with the same `OracleQuery` member values always lead the exact same `OracleReply`. +The rationale is that the oracle is queried individually by the computors and a quorum needs to agree on the exact same reply in order to confirm its correctness. +In order to satisfy this requirement, most oracle query structs will require: +- an oracle identifier, exactly specifying the source/provider, where to get the information, +- a timestamp about the exact time in case of information that varies with time, such as prices, +- additional specification which data is queried, such as a pair of currencies for prices or a + location for weather. + +If the oracle interface is supposed to support subscriptions, the `OracleQuery` struct must define a member named `timestamp` of the type `QPI::DateAndTime`. + +The size of `OracleQuery` is restricted by the transaction size. +The limit is available through the constant `MAX_ORACLE_QUERY_SIZE`. + + +### Oracle reply + +The `OracleReply` struct of the interface defines the output of the Oracle Machine, specifying which types of information are provided. + +For example, in the `Price` oracle, the `OracleReply` has the member variables `numerator` and `denominator` giving the exchange rate such that `currency1 = currency2 * numerator / denominator` at `timestamp` as given by the query. + +The size of both the `OracleReply` struct is restricted by the transaction size. +The limit is available through the constant `MAX_ORACLE_REPLY_SIZE`. + + +### Fees + +The interface defines the oracle fees through the static member functions `getQueryFee()` and, optionally, if subscriptions are supported, `getSubscriptionFee()`. +They must be declared as follows: + +```C++ +// mandatory: get fee for regular one-time query +static sint64 getQueryFee(const OracleQuery& query); + +// optional function: get one-time fee for subscription +static sint64 getSubscriptionFee(const OracleQuery& query, uint32 notifyPeriodInMilliseconds); +``` + +The one-time query fee needs to be paid for each call to `QUERY_ORACLE()` and as the amount of each user oracle query transaction. +It may depend on the specific query, for example, on the oracle (source providing the information). + +The subscription fee needs to be paid for each call to `SUBSCRIBE_ORACLE()`, which is usually once per epoch. +It may depend on the specific query and on the notification period, that is, how often the contract wants to get notified with a new value. + +For example, when writing these docs, the fee for a one-time `Price` query is 10 QU. +The fee for a `Price` subscription is 10000 QU for getting an update each minute, which means about 1 QU/query if the subscription is active in the full epoch. +A subscription querying each 2 or 3 minutes costs only 6500 QU. +The fee reduces again and again with a notification intervals of 4 minutes, 8 minutes, and following powers of 2. +While total cost of the subscription reduces, the cost per query increases (by design, because the potential efficiency gain by sharing queries between contracts reduces with the frequency). +See the comments in the source code in `src/oracle_interfaces/Price.h` for more details. + +The source code of the official Qubic Core repository and release should usually tell the current oracle fees. +However, the Quorum decides as usual in Qubic, because the computors running the Qubic Network may change the code, including the fee amounts. + + +### Adding new interfaces + +New oracle interfaces may be added by contract developers as required for their contracts with Pull Requests, see [How to Contribute](contributing.md). + +A new interface should be designed in a generic way, that allows to reuse it in other contracts and applications. +For example, even if only one oracle (information provider) is supported initially, there should be an oracle member in the `OracleQuery` struct for supporting others later. + +We recommend to start developing an interface by copying the file `src/oracle_interfaces/Price.h`, changing the name, and changing the content of the file. +The file must contain an oracle interface struct named the same as the filename stem, e.g., `Price` for `Price.h`. +The oracle interface struct is never instantiated, but its types and static members are available to contracts via `OI::[InterfaceName]`, for example, `OI::Price::OracleQuery` and `OI::Price::getQueryFee(query)`. + +Each oracle interface is internally identified through the `oracleInterfaceIndex`, a number identifying the interface. +It has to be defined as a static member of the interface struct as follows: + +```C++ +static constexpr uint32 oracleInterfaceIndex = ORACLE_INTERFACE_INDEX; +``` + +`ORACLE_INTERFACE_INDEX` is defined in the file `src\oracle_core\oracle_interfaces_def.h`, which includes all interface header files and is discussed later below. + +As mentioned in Sections above, the following structs and functions have to be defined as members of the interface struct: + +```C++ +struct OracleQuery +{ + // add input to OM +}; + +struct OracleReply +{ + // add output of OM +}; + +static sint64 getQueryFee(const OracleQuery& query) +{ + // Return query fee, which may depend on the specific query (for example on the oracle). +} +``` + +If the interface is supposed to support subscriptions, the `OracleQuery` struct must have a member `QPI::DateAndTime timestamp;`. +Further, the interface struct must define the following function: + +```C++ +static sint64 getSubscriptionFee(const OracleQuery& query, uint32 notifyPeriodInMilliseconds) +{ + // Return one-time fee for subscription +} +``` + +Additionally, the interface struct may contain other structs or convenience features for contracts using the oracle interface. + +All code in the interface header file must respect the same [C++ language feature restrictions as contracts](#restrictions-of-c-language-features). +These are checked with the [Qubic Contract Verification Tool](https://github.com/Franziska-Mueller/qubic-contract-verify). + +A new oracle interface has to be added file `src/oracle_core/oracle_interfaces_def.h`. +Search for "add new interface above this line" in this file to see, where to add references to new interface to make it available to contracts and the oracle engine. + +Another mandatory requirement for a new interface is adding a reference implementation of the oracle service counterpart in [Oracle Machine repository](https://github.com/qubic/oracle-machine/). +This repository references the original interface definition from the Qubic Core repository via a git submodule. +For testing before the new interface is merged to the official repository, we recommend to replace the submodule with a reference to your own fork of the Core. + +Please note that structs such as `OracleReply` may have some padding (gaps, unused bytes for better alignment in the memory). +Make sure that `OracleReply` is set to all-0 before setting the member data, so that alignment/padding bytes are initialized with 0 and that no memory content of the OM node is published on-chain. + + +## Notifications + +As mentioned above, `QUERY_ORACLE()` and `SUBSCRIBE_ORACLE()` just start the query and subscription asynchronously and return without a reply. +The contract is notified about success or error through an asynchronous call to a special notification user procedure, usually multiple ticks later (exception are a few error cases that trigger the notification immediately, such as not having enough QU to pay the fee). +Notifications are run by the system after execution of transactions (user procedures) but before `END_TICK` (with 0 invocation reward and originator/invocator `NULL_ID`). + + +### Defining notification procedures + +An oracle notification procedure must have the input type `OracleNotificationInput` and the output type `NoData`. +It may be defined with or without locals. + +For example, a notification procedure for the `Price` oracle may be defined like this: + +```C++ +typedef OracleNotificationInput NotifyPriceOracleReply_input; +typedef NoData NotifyPriceOracleReply_output; +struct NotifyPriceOracleReply_locals +{ + OI::Price::OracleQuery query; +}; + +PRIVATE_PROCEDURE_WITH_LOCALS(NotifyPriceOracleReply) +{ + if (input.status == ORACLE_QUERY_STATUS_SUCCESS) + { + // get and use query info if needed + if (!qpi.getOracleQuery(input.queryId, locals.query)) + return; + + // use example convenience function provided by oracle interface + if (!OI::Price::replyIsValid(input.reply)) + return; + + // process reply ... + } + else + { + // handle failure ... + } +} +``` + +The `OracleNotificationInput` input has the members: + +- `sint64 queryId`: ID of the oracle query that led to this notification (or -1 in case of an early error, before a query ID has been assigned), +- `sint32 subscriptionId`: ID of the oracle subscription or -1 in case of a one-time oracle query, +- `OracleInterface::OracleReply reply`: Oracle reply to query (type `OI::Price::OracleReply` in the example above), only valid if `status` is `ORACLE_QUERY_STATUS_SUCCESS`, +- `uint8 status`: Oracle query status as defined in `src/network_messages/common_def.h`; one of `ORACLE_QUERY_STATUS_SUCCESS`, `ORACLE_QUERY_STATUS_TIMEOUT`, `ORACLE_QUERY_STATUS_UNRESOLVABLE`, or `ORACLE_QUERY_STATUS_UNKNOWN` (in case of an early error, before the query has been started). + +Usually, the notification procedure should be a `PRIVATE_PROCEDURE` or `PRIVATE_PROCEDURE_WITH_LOCALS`. +If you define it as a `PUBLIC_PROCEDURE`, other contracts may invoke it, what you probably want to avoid. + + +### Registering notification procedures + +In order to make the procedure usable as a notification, it must be registered with `REGISTER_USER_PROCEDURE_NOTIFICATION()` in `REGISTER_USER_FUNCTIONS_AND_PROCEDURES`. + +However, it should **NOT** be registered for external access with `REGISTER_USER_PROCEDURE()` as most other user procedures. +Otherwise, if registered with the latter, any user can invoke your notification procedure through a transaction. + +In the example above, `REGISTER_USER_FUNCTIONS_AND_PROCEDURES` may look like this: + +```C++ +REGISTER_USER_FUNCTIONS_AND_PROCEDURES() +{ + REGISTER_USER_PROCEDURE_NOTIFICATION(NotifyPriceOracleReply); + + // REGISTER_USER_PROCEDURE calls, none for NotifyPriceOracleReply !!! + + // REGISTER_USER_FUNCTION calls +} +``` + + +## Query QPI + +### Sending out a query + +As mentioned above, oracles are queried asynchronously, because it takes at least 7 ticks until the reply is committed and revealed. + +A contract can initiate a query using the `QUERY_ORACLE()` macro, which takes the following parameters: + +- `OracleInterface`: Oracle interface struct of the interface to query, e.g., `OI::Price`, +- `query`: Instance of type `OracleInterface::OracleQuery` containing details about which oracle to query for which information, as defined by the specific oracle interface, +- `userProcNotification`: User notification procedure that shall be executed when the oracle reply is available or an error occurs (must be registered, see [Registering Notification Procedures](#registering-notification-procedures)), +- `timeoutMillisec`: Maximum number of milliseconds to wait for the reply. Reasonable values are 30000 or 60000 (30 or 60 seconds). Too low values may lead to always getting timeout errors. + +The macro returns the Oracle query ID that can be used to get the status of the query, or -1 on error. + +Here is an example of how to use this macro: + +```C++ +locals.queryId = QUERY_ORACLE(OI::Price, locals.priceOracleQuery, NotifyPriceOracleReply, 60000); +``` + +This call will automatically burn the oracle query fee as defined by the oracle interface. +More specifically, it will destroy the QUs without adding to the contract's execution fee reserve. +It will fail if the contract doesn't have enough QUs. + +The notification callback will be executed when the reply is available or on error. +The callback must be a user procedure of the contract calling `QUERY_ORACLE()` with the procedure input type `OracleNotificationInput` and `NoData` as output. +The procedure must be registered with `REGISTER_USER_PROCEDURE_NOTIFICATION()` in `REGISTER_USER_FUNCTIONS_AND_PROCEDURES`. + +In the notification callback, success is indicated by `input.status == ORACLE_QUERY_STATUS_SUCCESS`. +If an error happened before the query has been created and sent, `input.status` is `ORACLE_QUERY_STATUS_UNKNOWN` and `input.queryId` is -1 (invalid). +Other errors that may happen with valid `input.queryId` are `input.status == ORACLE_QUERY_STATUS_TIMEOUT` and `input.status == ORACLE_QUERY_STATUS_UNRESOLVABLE`. + +All queries, including pending queries are discarded at the end of the epoch. Contracts aren't notified in this case. + +An alternative way of initiating periodic queries is using subscriptions, see the [Subscription QPI](#subscription-qpi) + + +### Getting the query status by query ID + +A contract can get the status of any query by the query ID as in this example: + +```C++ +output.status = qpi.getOracleQueryStatus(input.queryId); +``` + +The returned status is one of the following: + +- `ORACLE_QUERY_STATUS_UNKNOWN`: Query not found / not valid. +- `ORACLE_QUERY_STATUS_PENDING`: Query is being processed. +- `ORACLE_QUERY_STATUS_COMMITTED`: The Quorum has committed to an oracle reply, but it has not been revealed yet. +- `ORACLE_QUERY_STATUS_SUCCESS`: The oracle reply has been confirmed and is available. +- `ORACLE_QUERY_STATUS_UNRESOLVABLE`: No valid oracle reply is available, because computors disagreed about the value. +- `ORACLE_QUERY_STATUS_TIMEOUT`: No valid oracle reply is available and timeout has hit. + + +### Getting the query by query ID + +A contract can get the query data of any query given it knows the query ID and the associated oracle interface. Example: + +```C++ +if (qpi.getOracleQuery(input.queryId, locals.priceQuery)) +{ + // use locals.priceQuery +} +``` + +This tries to get the query data associated with the query identified by `queryId`. +If `queryId` is valid and matches with the oracle interface given via the template parameter (`OI::Price` in this example), `locals.priceQuery` (which must be of type `OI::Price::OracleQuery` in this example) is set and the function returns true. Otherwise it returns false. + + +### Getting the reply by query ID + +A contract can get the reply data of any query given it knows the query ID and the associated oracle interface. Example: + +```C++ +if (qpi.getOracleReply(input.queryId, locals.priceReply)) +{ + // use locals.priceReply +} +``` + +This functions returns wether `queryId` is found, matches the oracle interface, and a valid reply is available (query status is `ORACLE_QUERY_STATUS_SUCCESS`). +If all this is true, the function copies the oracle reply into `locals.priceReply`, which must be of type `OI::Price::OracleReply` in this example. + + +## Subscription QPI + +Subscriptions are a cheaper and more efficient way to query time-dependent information, such as prices, regularly. +A subscription repeatedly sends the same query, only changing the query timestamp. +The subscription queries may be shared by multiple contracts automatically. + +After subscribing, updated information is pushed to the subscriber contract in defined intervals as requested. +Internally, a scheduler takes care for translating subscriptions into bundled one-time queries, whose reply may be delivered to multiple contracts. + +Subscriptions end with the epoch. That is, contracts must subscribe again in a new epoch, even if the epoch transition is seamless. + +A subscriptions usually costs a higher fee than a single one-time query, but a lower fee than replacing the subscription with recurring one-time queries (because resources are saved when multiple contracts subscribe to the same oracle “channel”). + + +### Subscribing + +A contract can subscribe for regularly querying an oracle using the macro `SUBSCRIBE_ORACLE()`, which expects the following parameters: + +- `OracleInterface`: Oracle interface struct of the interface to query that supports subscriptions, e.g., `OI::Price`, +- `query`: Instance of type `OracleInterface::OracleQuery` that specifies which information is requested, e.g., the oracle and currencies in `OI::Price`. + It must have a member `DateAndTime timestamp` that can be set by the scheduler. +- `notificationCallback`: User notification procedure that shall be executed when the oracle reply is available or an error occurs (must be registered, see [Registering Notification Procedures](#registering-notification-procedures)), +- `notificationPeriodInMilliseconds`: Number of milliseconds between consecutive queries/replies that the contract is notified about. Currently, only multiples of 60000 are supported and other values are rejected with an error. +- `notifyWithPreviousReply`: Whether to immediately notify this contract with the most up-to-date value if any is available. + +The macro returns the Oracle subscription ID or -1 on error. + +Here is an example of how to use this macro: + +```C++ +output.subscriptionId = SUBSCRIBE_ORACLE(OI::Price, input.priceOracleQuery, NotifyPriceOracleReply, input.subscriptionPeriodMilliseconds, input.notifyPreviousValue); +``` + +Subscriptions automatically expire at the end of each epoch. +So, a common pattern is to call `SUBSCRIBE_ORACLE()` in `BEGIN_EPOCH`. + +Subscriptions facilitate sharing common oracle queries among multiple contracts. +This saves network resources and allows to provide a fixed-price subscription for the whole epoch, which is usually much cheaper than the equivalent series of +individual `QUERY_ORACLE()` calls. + +The `SUBSCRIBE_ORACLE()` call will automatically burn the oracle subscription fee as defined by the oracle interface +(burning without adding to the contract's execution fee reserve). +It will fail if the contract doesn't have enough QUs. + +The notification callback will be executed when the reply is available or on error. +The callback must be a user procedure of the contract calling `SUBSCRIBE_ORACLE()` with the procedure input type `OracleNotificationInput` and `NoData` as output. +The procedure must be registered with `REGISTER_USER_PROCEDURE_NOTIFICATION()` in `REGISTER_USER_FUNCTIONS_AND_PROCEDURES`. + +In the notification callback, success is indicated by `input.status == ORACLE_QUERY_STATUS_SUCCESS`. +If an error happened before the query has been created and sent, `input.status` is `ORACLE_QUERY_STATUS_UNKNOWN` and `input.queryId` is -1 (invalid). +Other errors that may happen with valid `input.queryId` are `input.status == ORACLE_QUERY_STATUS_TIMEOUT` and `input.status == ORACLE_QUERY_STATUS_UNRESOLVABLE`. +The timeout of subscription queries is always 60000 milliseconds. + +A contract may subscribe to the same oracle interface with multiple different queries. +However, it cannot subscribe with the same query multiple times. +In order to change the notification period of an existing query, it needs to be unsubscribed first and subscribed again afterwards. + + +### Unsubscribing + +A contract can unsubscribe from an own subscription with the subscription ID returned by the `SUBSCRIBE_ORACLE()` call as illustrated in the following example: + +```C++ +output.success = qpi.unsubscribeOracle(input.subscriptionId); +``` + +The function returns true if the subscription given by the ID has been stopped (false means that the ID is invalid). + +If there is a pending query initiated for this subscription while unsubscribing, the contract will still be notified for that query even after unsubscribing. +However, no new queries for this contract will be generated. + + +## IDs + +### Query ID + +The query ID is a signed 64-bit integer, with values >= 0 being reserved for valid query IDs and values < 0 reserved for signalling errors. + +Query IDs are unique. +They are constructed from the tick, when the query was initiated and an index during the tick. + +For user queries, the index is given by the index of the query transaction in the tick data. +For contract one-time queries and subscription queries, the index is generated sequentially, starting at the maximum number of transactions per tick. + +With that index and the query tick, the ID is generated `queryId = (tick << 31) + index` (shift the tick by 31 bits and add the index). + + +### Subscription ID + +The subscription ID is a signed 32-bit integer. +Valid IDs are >= 0. +Negative values are reserved for signaling errors. + +A subscription ID is bound to an oracle interface and specific initial query passed to `SUBSCRIBE_ORACLE()`. +Multiple contracts (subscribers) may share the same subscription ID, but have individual notification periods. + +Subscription IDs are generated sequentially, that is, if there are N subscriptions they will have the IDs 0, 1, ..., N-1. + + +## Tools + +The command-line tool [qubic-cli](https://github.com/qubic/qubic-cli) provides useful commands for debugging and experimenting with oracles. +For example: + +- `qubic-cli [...] -queryoracle`: Command for generating a user query to an oracle. Run this to get help how to use it. +- `qubic-cli [...] -getoraclequery`: Command for getting information about oracle queries. Run this to get help how to use it. +- `qubic-cli [...] -getoraclesubscription`: Command for getting information about oracle subscriptions. Run this to get help how to use it. +- `qubic-cli [...] -querypriceviacontract`: Send price query via contract. Useful for testing contract queries and subscriptions. Run this to get help how to use it. + +Another useful tool for debugging your contract in the Core when running a testnet is [qlogging](https://github.com/qubic/qlogging/). +This prints the event log messages emitted by the core, including messages for oracle query state changes and subscribing/unsubscribing. + + +## Implementation details + +![OracleEngine](OracleEngine.png "OracleEngine") diff --git a/src/assets/net_msg_impl.h b/src/assets/net_msg_impl.h index a8afafb40..2d417860d 100644 --- a/src/assets/net_msg_impl.h +++ b/src/assets/net_msg_impl.h @@ -135,14 +135,14 @@ static void processRequestAssetsSendRecord(Peer* peer, RequestResponseHeader* re static void processRequestAssets(Peer* peer, RequestResponseHeader* header) { - // check size of recieved message (request by universe index may be smaller than sizeof(RequestAssets)) + // check size of received message (request by universe index may be smaller than sizeof(RequestAssets)) if (!header->checkPayloadSizeMinMax(sizeof(RequestAssets::byUniverseIdx), sizeof(RequestAssets))) return; RequestAssets* request = header->getPayload(); if (request->assetReqType != RequestAssets::requestByUniverseIdx && !header->checkPayloadSize(sizeof(RequestAssets))) return; - // initalize output message (with siblings because the variant without siblings is just a subset) + // initialize output message (with siblings because the variant without siblings is just a subset) struct { RequestResponseHeader header; @@ -152,7 +152,7 @@ static void processRequestAssets(Peer* peer, RequestResponseHeader* header) response.header.setType(RespondAssets::type()); response.header.setDejavu(header->dejavu()); - // size of output message depends on whether sibilings are requested + // size of output message depends on whether siblings are requested if (request->byFilter.flags & RequestAssets::getSiblings) response.header.setSize(); else diff --git a/src/contracts/qpi.h b/src/contracts/qpi.h index a75490b65..a39cf9a40 100644 --- a/src/contracts/qpi.h +++ b/src/contracts/qpi.h @@ -2499,7 +2499,7 @@ namespace QPI * * - ORACLE_QUERY_STATUS_UNKNOWN: Query not found / not valid. * - ORACLE_QUERY_STATUS_PENDING: Query is being processed. - * - ORACLE_QUERY_STATUS_COMMITTED: The quorum has commited to a oracle reply, but it has not been revealed yet. + * - ORACLE_QUERY_STATUS_COMMITTED: The quorum has committed to an oracle reply, but it has not been revealed yet. * - ORACLE_QUERY_STATUS_SUCCESS: The oracle reply has been confirmed and is available. * - ORACLE_QUERY_STATUS_UNRESOLVABLE: No valid oracle reply is available, because computors disagreed about the value. * - ORACLE_QUERY_STATUS_TIMEOUT: No valid oracle reply is available and timeout has hit. @@ -2532,9 +2532,9 @@ namespace QPI template struct OracleNotificationInput { - sint64 queryId; ///< ID of the oracle query that led to this notification. - sint32 subscriptionId; ///< ID of the oracle subscription or -1 in case of a pure oracle query. - uint8 status; ///< Oracle query status as defined in `network_messages/common_def.h` + sint64 queryId; ///< ID of the oracle query that led to this notification. + sint32 subscriptionId; ///< ID of the oracle subscription or -1 in case of a one-time oracle query. + uint8 status; ///< Oracle query status as defined in `network_messages/common_def.h` uint8 __reserved0; uint16 __reserved1; typename OracleInterface::OracleReply reply; ///< Oracle reply if status == ORACLE_QUERY_STATUS_SUCCESS @@ -3083,22 +3083,24 @@ namespace QPI /** * @brief Initiate oracle query that will lead to notification later. + * @param OracleInterface Oracle interface struct of interface to query, e.g., OI::Price * @param query Details about which oracle to query for which information, as defined by a specific oracle interface. * @param userProcNotification User procedure that shall be executed when the oracle reply is available or an error occurs. * @param timeoutMillisec Maximum number of milliseconds to wait for reply. - * @return Oracle query ID that can be used to get the status of the query, or 0 on error. + * @return Oracle query ID that can be used to get the status of the query, or -1 on error. * * This will automatically burn the oracle query fee as defined by the oracle interface (burning without * adding to the contract's execution fee reserve). It will fail if the contract doesn't have enough QU. * * The notification callback will be executed when the reply is available or on error. - * The callback must be a user procedure of the contract calling qpi.queryOracle() with the procedure input type + * The callback must be a user procedure of the contract calling QUERY_ORACLE() with the procedure input type * OracleNotificationInput and NoData as output. The procedure must be registered with * REGISTER_USER_PROCEDURE_NOTIFICATION() in REGISTER_USER_FUNCTIONS_AND_PROCEDURES(). - * Success is indicated by input.status == ORACLE_QUERY_STATUS_SUCCESS. + * + * In the notification callback, success is indicated by input.status == ORACLE_QUERY_STATUS_SUCCESS. * If an error happened before the query has been created and sent, input.status is ORACLE_QUERY_STATUS_UNKNOWN - * and input.queryID is -1 (invalid). - * Other errors that may happen with valid input.queryID are input.status == ORACLE_QUERY_STATUS_TIMEOUT and + * and input.queryId is -1 (invalid). + * Other errors that may happen with valid input.queryId are input.status == ORACLE_QUERY_STATUS_TIMEOUT and * input.status == ORACLE_QUERY_STATUS_UNRESOLVABLE. */ #define QUERY_ORACLE(OracleInterface, query, userProcNotification, timeoutMillisec) qpi.__qpiQueryOracle(query, userProcNotification, __id_##userProcNotification, timeoutMillisec) @@ -3110,14 +3112,14 @@ namespace QPI * @param notificationPeriodInMilliseconds Number of milliseconds between consecutive queries/replies that the contract * is notified about. Currently, only multiples of 60000 are supported and other values are rejected with an error. * @param notifyWithPreviousReply Whether to immediately notify this contract with the most up-to-date value if any is available. - * @return Oracle subscription ID that can be used to get the status of the subscription, or -1 on error. + * @return Oracle subscription ID or -1 on error. * * Subscriptions automatically expire at the end of each epoch. So, a common pattern is to call SUBSCRIBE_ORACLE * in BEGIN_EPOCH. * * Subscriptions facilitate sharing common oracle queries among multiple contracts. This saves network resources and allows * to provide a fixed-price subscription for the whole epoch, which is usually much cheaper than the equivalent series of - * individual qpi.queryOracle() calls. + * individual QUERY_ORACLE() calls. * * The SUBSCRIBE_ORACLE call will automatically burn the oracle subscription fee as defined by the oracle interface * (burning without adding to the contract's execution fee reserve). It will fail if the contract doesn't have enough QU. @@ -3126,12 +3128,17 @@ namespace QPI * The callback must be a user procedure of the contract calling SUBSCRIBE_ORACLE with the procedure input type * OracleNotificationInput and NoData as output. The procedure must be registered with * REGISTER_USER_PROCEDURE_NOTIFICATION() in REGISTER_USER_FUNCTIONS_AND_PROCEDURES(). - * Success is indicated by input.status == ORACLE_QUERY_STATUS_SUCCESS. + * + * In the notification callback, success is indicated by input.status == ORACLE_QUERY_STATUS_SUCCESS. * If an error happened before the query has been created and sent, input.status is ORACLE_QUERY_STATUS_UNKNOWN - * and input.queryID is -1 (invalid). - * Other errors that may happen with valid input.queryID are input.status == ORACLE_QUERY_STATUS_TIMEOUT and + * and input.queryId is -1 (invalid). + * Other errors that may happen with valid input.queryId are input.status == ORACLE_QUERY_STATUS_TIMEOUT and * input.status == ORACLE_QUERY_STATUS_UNRESOLVABLE. * The timeout of subscription queries is always 60000 milliseconds. + * + * A contract may subscribe to the same oracle interface with multiple different queries. + * However, it cannot subscribe with the same query multiple times. + * In order to change the notification period of an existing query, it needs to be unsubscribed first and subscribed again afterwards. */ #define SUBSCRIBE_ORACLE(OracleInterface, query, userProcNotification, notificationPeriodInMilliseconds, notifyWithPreviousReply) qpi.__qpiSubscribeOracle(query, userProcNotification, __id_##userProcNotification, notificationPeriodInMilliseconds, notifyWithPreviousReply) diff --git a/src/network_messages/common_def.h b/src/network_messages/common_def.h index 3b0d8538f..732c14879 100644 --- a/src/network_messages/common_def.h +++ b/src/network_messages/common_def.h @@ -56,7 +56,7 @@ constexpr uint8_t ORACLE_QUERY_TYPE_USER_QUERY = 2; constexpr uint8_t ORACLE_QUERY_STATUS_UNKNOWN = 0; ///< Query not found / valid. constexpr uint8_t ORACLE_QUERY_STATUS_PENDING = 1; ///< Query is being processed. -constexpr uint8_t ORACLE_QUERY_STATUS_COMMITTED = 2; ///< The quorum has commited to a oracle reply, but it has not been revealed yet. +constexpr uint8_t ORACLE_QUERY_STATUS_COMMITTED = 2; ///< The quorum has committed to an oracle reply, but it has not been revealed yet. constexpr uint8_t ORACLE_QUERY_STATUS_SUCCESS = 3; ///< The oracle reply has been confirmed and is available. constexpr uint8_t ORACLE_QUERY_STATUS_UNRESOLVABLE = 5;///< No valid oracle reply is available, because computors disagreed about the value. constexpr uint8_t ORACLE_QUERY_STATUS_TIMEOUT = 4; ///< No valid oracle reply is available and timeout has hit. diff --git a/src/oracle_core/oracle_interfaces_def.h b/src/oracle_core/oracle_interfaces_def.h index e1db23125..458b8e497 100644 --- a/src/oracle_core/oracle_interfaces_def.h +++ b/src/oracle_core/oracle_interfaces_def.h @@ -13,6 +13,8 @@ namespace OI #include "oracle_interfaces/Mock.h" #undef ORACLE_INTERFACE_INDEX +// add new interface above this line (define ORACLE_INTERFACE_INDEX, include the header file and undef ORACLE_INTERFACE_INDEX) + #define DEFINE_ORACLE_INTERFACE(Interface) {sizeof(Interface::OracleQuery), sizeof(Interface::OracleReply)} constexpr struct { @@ -21,6 +23,7 @@ namespace OI } oracleInterfaces[] = { DEFINE_ORACLE_INTERFACE(Price), DEFINE_ORACLE_INTERFACE(Mock), + // add new interface above this line (with DEFINE_ORACLE_INTERFACE; the order must match the interfaces indices) }; static constexpr uint32_t oracleInterfacesCount = sizeof(oracleInterfaces) / sizeof(oracleInterfaces[0]); @@ -49,6 +52,7 @@ namespace OI REGISTER_ORACLE_INTERFACE(Price); REGISTER_ORACLE_INTERFACE(Mock); + // add new interface above this line (with REGISTER_ORACLE_INTERFACE) for (uint32_t idx = 0; idx < oracleInterfacesCount; ++idx) { diff --git a/src/oracle_interfaces/Price.h b/src/oracle_interfaces/Price.h index ca2d51155..4cb367adf 100644 --- a/src/oracle_interfaces/Price.h +++ b/src/oracle_interfaces/Price.h @@ -7,8 +7,8 @@ using namespace QPI; * the same input and output structs (OracleQuery and OracleReply). * * It also defines the oracle query and subscription fees through the member functions getQueryFee() and -* getSubscriptionFee(). The subscription fee needs to be paid for each call to qpi.subscribeOracle(), -* which is usually once per epoch. The query fee needs to be paid for each call to qpi.queryOracle() +* getSubscriptionFee(). The subscription fee needs to be paid for each call to SUBSCRIBE_ORACLE(), +* which is usually once per epoch. The query fee needs to be paid for each call to QUERY_ORACLE() * and as the amount of each user oracle query transaction. * * Each oracle interface is internally identified through the oracleInterfaceIndex. diff --git a/src/private_settings.h b/src/private_settings.h index b8737a8d3..4b267542f 100644 --- a/src/private_settings.h +++ b/src/private_settings.h @@ -27,6 +27,8 @@ static const unsigned char whiteListPeers[][4] = { }; */ +// Enter static IPs of one or multiple oracle machine node(s). This node will connect to these and try to keep the +// connection open for low latency. The oracle machine nodes also need to whitelist the IP of this core node. static const unsigned char oracleMachineIPs[][4] = { {127, 0, 0, 1}, // REMOVE THIS ENTRY AND REPLACE IT WITH YOUR OWN IP ADDRESSES }; diff --git a/src/qubic.cpp b/src/qubic.cpp index 3121d484e..fed64dd8d 100644 --- a/src/qubic.cpp +++ b/src/qubic.cpp @@ -3438,7 +3438,7 @@ static void processTick(unsigned long long processorNumber) PROFILE_SCOPE_END(); } - // Generate subscription queries (may create queries that immediately timout if the network was stuck) + // Generate subscription queries (may create queries that immediately timeout if the network was stuck) oracleEngine.generateSubscriptionQueries(); // Check for oracle query timeouts (may schedule notification) From 6f03fff9880e203084f50875d5287186f67cb9b1 Mon Sep 17 00:00:00 2001 From: fnordspace Date: Wed, 18 Mar 2026 09:46:27 +0100 Subject: [PATCH 15/15] Adjust inital tick --- src/public_settings.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/public_settings.h b/src/public_settings.h index 22eaa320c..65c7c5d4b 100644 --- a/src/public_settings.h +++ b/src/public_settings.h @@ -71,7 +71,7 @@ static_assert(AUTO_FORCE_NEXT_TICK_THRESHOLD* TARGET_TICK_DURATION >= PEER_REFRE // Epoch and initial tick for node startup #define EPOCH 205 -#define TICK 46460000 +#define TICK 46310000 #define TICK_IS_FIRST_TICK_OF_EPOCH 1 // Set to 0 if the network is restarted during the EPOCH with a new initial TICK #define ARBITRATOR "AFZPUAIYVPNUYGJRQVLUKOPPVLHAZQTGLYAAUUNBXFTVTAMSBKQBLEIEPCVJ"