Last updated

Witness Servers

[Source]

(Requires the XChainBridge amendment )

A witness server acts as a neutral witness for transactions between a locking chain and an issuing chain. It listens to the door accounts on both sides of a bridge and signs attestations that confirm a transaction occurred. They are essentially acting as an oracle to “prove” that value was locked or burned on a source account, which allows the recipient to then claim (via minting or unlocking) the equivalent funds on the destination account.

The bridge between the locking chain and the issuing chain includes the following information in its configuration:

  • Witness servers that monitor transactions on the bridge. You can choose one or more witness servers.
  • Fee for witness servers for their service.

Anyone can run a witness server. However, the burden is on the participants of the issuing chain to evaluate the reliability of witness servers. If you run a witness server, you must also run a rippled node and sync it to the chain the witness server needs access to.

Note: Issuing chains may choose to configure a bridge with only one witness server initially and run the witness server itself. This strategy is helpful in the initial period, when the issuing chain hasn't established itself yet in the marketplace.

Witness Server Configuration

The witness server takes a JSON configuration file, specified using the --conf command-line argument.

Example Configuration JSON

{
  "LockingChain": {
    "Endpoint": {
      "Host": "127.0.0.1",
      "Port": 6005
    },
    "TxnSubmit": {
      "ShouldSubmit": true,
      "SigningKeySeed": "shUe3eSgGK4e6xMFuCakZnxsMN1uk",
      "SigningKeyType": "ed25519",
      "SubmittingAccount": "rpFp36UHW6FpEcZjZqq5jSJWY6UCj3k4Es"
    },
    "RewardAccount": "rpFp36UHW6FpEcZjZqq5jSJWY6UCj3k4Es"
  },
  "IssuingChain": {
    "Endpoint": {
      "Host": "127.0.0.1",
      "Port": 6007
    },
    "TxnSubmit": {
      "ShouldSubmit": true,
      "SigningKeySeed": "shUe3eSgGK4e6xMFuCakZnxsMN1uk",
      "SigningKeyType": "ed25519",
      "SubmittingAccount": "rpFp36UHW6FpEcZjZqq5jSJWY6UCj3k4Es"
    },
    "RewardAccount": "rpFp36UHW6FpEcZjZqq5jSJWY6UCj3k4Es"
  },
  "RPCEndpoint": {
    "Host": "127.0.0.1",
    "Port": 6010
  },
  "DBDir": "/var/lib/witness/witness01/db",
  "LogFile": "/var/log/witness/witness01.log",
  "SigningKeySeed": "spkHEwDKeChm8PAFApLkF1E2sDs6t",
  "SigningKeyType": "ed25519",
  "XChainBridge": {
    "LockingChainDoor": "r3nCVTbZGGYoWvZ58BcxDmiMUU7ChMa1eC",
    "LockingChainIssue": {
      "currency": "XRP"
    },
    "IssuingChainDoor": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
    "IssuingChainIssue": {
      "currency": "XRP"
    }
  },
  "Admin": {
    "Username": "username01",
    "Password": "password01"
  }
}

Configuration Fields

Field NameJSON TypeRequired?Description
AdminObjectNoThe Username and Password fields (as strings) for privileged requests to the witness server. Note: Both or none of the admin fields must be set.
IssuingChainObjectYesThe parameters for interacting with the issuing chain.
LockingChainObjectYesThe parameters for interacting with the locking chain.
RPCEndpointObjectYesThe endpoint for RPC requests to the witness server.
LogFileStringYesThe location of the log file.
LogLevelStringYesThe level of logs to store in the log file. The options are All, Trace, Debug, Info, Warning, Error, Fatal, Disabled, and None.
DBDirStringYesThe location of the directory where the databases are stored.
SigningKeySeedStringYesThe seed that the witness server should use to sign its attestations.
SigningKeyTypeStringYesThe algorithm used to encode the SigningKeySeed. The options are secp256k1 and ed25519.
XChainBridgeXChainBridgeYesThe bridge that the witness server is monitoring.

IssuingChain and LockingChain Fields

Field NameJSON TypeRequired?Description
EndpointObjectYesThe websocket endpoint of a rippled node synced with the chain. Note: The same person needs to control the rippled node and witness server.
TxnSubmitObjectYesThe parameters for transaction submission on the chain.
RewardAccountStringYesThe account that should receive the witness's share of the SignatureReward on the chain.

Endpoint Fields

Field NameJSON TypeRequired?Description
HostStringYesThe IP address of the rippled node. Note: This accepts an IPv4 address or URL.
PortStringYesThe port used for the websocket endpoint.

RPCEndpoint Fields

Field NameJSON TypeRequired?Description
HostStringYesThe IP address of the witness server for RPC requests. Note: This accepts an IPv4 address or URL.
PortStringYesThe port used for the websocket endpoint.

TxnSubmit Fields

Field NameJSON TypeRequired?Description
ShouldSubmitBooleanYesA boolean indicating whether or not the witness server should submit transactions on the locking chain.
SigningKeySeedStringNoThe seed that the witness server should use to sign its transactions on the locking chain. This is required if ShouldSubmit is true.
SigningKeyTypeStringNoThe algorithm used to encode the SigningKeySeed. The options are secp256k1 and ed25519. This is required if ShouldSubmit is true.
SubmittingAccountStringNoThe account from which the XChainAddClaimAttestation and XChainAddAccountCreateAttestation transactions should be sent. This is required if ShouldSubmit is true.

XChainBridge Fields

FieldJSON TypeInternal TypeRequired?Description
IssuingChainDoorStringAccountYesThe door account on the issuing chain. For an XRP-XRP bridge, this must be the genesis account (the account that is created when the network is first started, which contains all of the XRP).
IssuingChainIssueIssueIssueYesThe asset that is minted and burned on the issuing chain. For an IOU-IOU bridge, the issuer of the asset must be the door account on the issuing chain, to avoid supply issues.
LockingChainDoorStringAccountYesThe door account on the locking chain.
LockingChainIssueIssueIssueYesThe asset that is locked and unlocked on the locking chain.